更新飛機(jī)票一張 Swagger 2 與 OpenAPI 3
元數(shù)據(jù)
- 每個(gè)Swagger規(guī)范都以Swagger版本開始
swagger: "2.0"
- 需要指定API的info-title,description（可選）,version（API版本,不是文件版本/Swagger版本）
info:
title: Instruction API
description:this is the API's description
version:1.0.0
- version 可以是自定義字符串，eg:1.0-beta,2018-02-02等
- description 可以使多行的
- info 中也可以支持其他信息對(duì)象，例如license, contact等
API調(diào)用的基礎(chǔ)URL
所有API調(diào)用的基礎(chǔ)URL由host , schemes , basePath（根級(jí)別）組成
host: api.instruction.com
basePath: /example
schemes:
- https
基礎(chǔ)路徑的設(shè)置已經(jīng)完成，若是加上端點(diǎn)/users就可以形成完整的路徑了：
<scheme>://<host>/<basePath>/users
路徑
API路徑paths和操作在API規(guī)范的全局部分定義，GET /用戶可以用以下來描述：
paths:
/users:
get:
summary:Returns a list of users.
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK
可以理解為是相對(duì)路徑，完整路徑如下：
scheme://host/basePath/path
- 支持路徑模版：
意味著您可以使用花括號(hào){}將URL的部分標(biāo)記為路徑參數(shù)：
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: Parameter description in Markdown.
responses:
200:
description: OK
eg: /users/1
Consumes和Produces定義
- consumes：指定處理請(qǐng)求的提交內(nèi)容類型（Content-Type）
- produces：指定返回的內(nèi)容類型，僅當(dāng)request請(qǐng)求頭中的（Accept）中包含指定類型才可以
consumes:
- application/json
- application/xml
produces:
- application/json
- application/xml
- 這里的類型均為MIME類型
- consumes只影響與POST，PUT和PATCH等請(qǐng)求主體的操作。對(duì)于像GET這樣的無(wú)人機(jī)操作，它會(huì)被忽略
響應(yīng)
對(duì)于每個(gè)操作，可以定義可能的狀態(tài)代碼，以及schema響應(yīng)主體。schema可以通過內(nèi)聯(lián)定義或從外部定義引用$ref(如果多個(gè)響應(yīng)使用相同的模式，可以在根級(jí)定義并通過引用$ref)。還可以為不同的內(nèi)容類型提供示例響應(yīng)
paths:
/users/{userId}:
get:
summary: 根據(jù)用戶ID返回一個(gè)對(duì)象 user.
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: 根據(jù)ID返回對(duì)象
responses:
200:
description: User成功獲取
schema:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: BlingBlingY
400:
description:輸入值不合法，不是數(shù)字.
schema:
$ref: "#/definitions/User"
404:
description: 不存在該用戶.
default:
description: 未知錯(cuò)誤
definitions:
User:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
更多信息可以參考，響應(yīng)詳情
輸入和輸出模型
全局的definitions允許定義通用數(shù)據(jù)結(jié)構(gòu)。任何時(shí)候無(wú)論是request還是response,schema里需要用到，都可以通過$ref 來引用它們
例如：
{
"id": 4,
"name": "Arthur Dent"
}
可以表示為：
definitions:
User:
properties:
id:
type: integer
name:
type: string
# Both properties are required
required:
- id
- name
在請(qǐng)求主體模式和響應(yīng)主體模式中引用:
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
responses:
200:
description: OK
schema:
$ref: '#/definitions/User'
/users:
post:
summary: Creates a new user.
parameters:
- in: body
name: user
schema:
$ref: '#/definitions/User'
responses:
200:
description: OK
認(rèn)證
在API中使用的身份驗(yàn)證關(guān)鍵詞：securityDefinitions和security
securityDefinitions:
BasicAuth:
type: basic
security:
- BasicAuth: []
- 目前API支持的三種認(rèn)證方法：
- 基本認(rèn)證 - BasicAuth
- API密鑰 - ApiKey
- OAuth2 公共流程
- securityDefinitions來定義該API支持的所有身份驗(yàn)證類型
securityDefinitions:
BasicAuth:
type: basic
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
OAuth2:
type: oauth2
flow: accessCode
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
read: Grants read access
write: Grants write access
admin: Grants read and write access to administrative information
在定義了安全機(jī)制后securityDefinitions，您可以security分別在根級(jí)別或操作級(jí)別上添加該部分，將它們應(yīng)用于整個(gè)API或單個(gè)操作。
在根級(jí)別上使用時(shí)，security將指定的安全機(jī)制全局應(yīng)用于所有API操作，除非在操作級(jí)別上被覆蓋。在以下示例中，可以使用API??密鑰或OAuth 2對(duì)API調(diào)用進(jìn)行身份驗(yàn)證.ApiKeyAuth和OAuth2名稱是指上文定義過的安全機(jī)制securityDefinitions
security:
- ApiKeyAuth: []
- OAuth2: [read, write]
全局security可以在個(gè)別操作中被覆蓋，從而可以使用不同的認(rèn)證類型，有的根本不認(rèn)證，如下例：
paths:
/billing_info:
get:
summary: Gets the account billing info
security:
- OAuth2: [admin] # Use OAuth with a different scope
responses:
200:
description: OK
401:
description: Not authenticated
403:
description: Access token does not have the required scope
/ping:
get:
summary: Checks if the server is running
security: [] # No security
responses:
200:
description: Server is up and running
default:
description: Something is wrong
3.多種驗(yàn)證類型
security模塊可使用邏輯OR和AND組合安全要求，來實(shí)現(xiàn)所需的結(jié)果
security: # A OR B
- A
- B
security: # A AND B
- A
B
security: # (A AND B) OR (C AND D)
- A
B
- C
D
- 使用基本身份驗(yàn)證或API密鑰：
security:
- basicAuth: []
- apiKey: []
security:
- apiKey1: []
apiKey2: []
- API需要在請(qǐng)求中包含一對(duì)API密鑰：
security:
- apiKey1: []
apiKey2: []
- 使用OAuth 2或一對(duì)API密鑰：
security:
- oauth2: [scope1, scope2]
- apiKey1: []
apiKey2: []
