Swagger

Swagger 規格

一個 API Design 相關的東東,找時間補完它。

Version 2.0

"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 參照 RFC 2119

Definitions

Path Templating ({})

Mime Types RFC 6838

HTTP Status Codes RFC 7231 IANA Status Code Registry

Specification

Format

All field names in the specification are case sensitive.

File Structure

$ref

By convention, the Swagger specification file is named swagger.json.

Data Types

Schema

SWAGGER OBJECT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
swagger: '2.0' # require

info: # require
title: Uber API # require
version: 1.0.0 # require
description: Move your app forward with the Uber API
termsOfService: string
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
contact:
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io

host: api.uber.com

basePath: /v1

schemes:
- https

consumes:
- string

produces:
- application/json

SWAGGER OBJECT Path

1
2
3
4
5
6
7
8
9
10
11
12
# /{path}
/pets:
$ref: string
get:Operation Object
put:Operation Object
post:Operation Object
delete:Operation Object
options:Operation Object
head:Operation Object
patch:Operation Object
parameters:
- Parameter Object | Reference Object
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
tags:
- pet
summary: Updates a pet in the store with form data
description: ""
externalDocs: External Documentation Object
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
- application/xml
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
type: string
- name: name
in: formData
description: Updated name of the pet
required: false
type: string
- name: status
in: formData
description: Updated status of the pet
required: false
type: string
responses:
'200':
description: Pet updated.
'405':
description: Invalid input
schemes:
- string
deprecated: false
security:
# OAuth2 Security Requirement
- petstore_auth:
- write:pets
- read:pets

Ref

$ref: '#/definitions/Pet'
$ref: 'Pet.yaml'
$ref: 'definitions.yaml#/Pet'


go-swagger

安裝及更新

go get -u github.com/go-swagger/go-swagger/cmd/swagger

轉換 yaml -> json

swagger generate spec -i ./swagger.yaml -o ./swagger.json


RAML