更新飞机票一张 Swagger 2 与 OpenAPI 3
元数据
- 每个Swagger规范都以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 中也可以支持其他信息对象，例如license, contact等
API调用的基础URL
所有API调用的基础URL由host , schemes , basePath（根级别）组成
host: api.instruction.com
basePath: /example
schemes:
- https
基础路径的设置已经完成，若是加上端点/users就可以形成完整的路径了：
<scheme>://<host>/<basePath>/users
路径
API路径paths和操作在API规范的全局部分定义，GET /用户可以用以下来描述：
paths:
/users:
get:
summary:Returns a list of users.
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK
可以理解为是相对路径，完整路径如下：
scheme://host/basePath/path
- 支持路径模版：
意味着您可以使用花括号{}将URL的部分标记为路径参数：
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：指定处理请求的提交内容类型（Content-Type）
- produces：指定返回的内容类型，仅当request请求头中的（Accept）中包含指定类型才可以
consumes:
- application/json
- application/xml
produces:
- application/json
- application/xml
- 这里的类型均为MIME类型
- consumes只影响与POST，PUT和PATCH等请求主体的操作。对于像GET这样的无人机操作，它会被忽略
响应
对于每个操作，可以定义可能的状态代码，以及schema响应主体。schema可以通过内联定义或从外部定义引用$ref(如果多个响应使用相同的模式，可以在根级定义并通过引用$ref)。还可以为不同的内容类型提供示例响应
paths:
/users/{userId}:
get:
summary: 根据用户ID返回一个对象 user.
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: 根据ID返回对象
responses:
200:
description: User成功获取
schema:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: BlingBlingY
400:
description:输入值不合法，不是数字.
schema:
$ref: "#/definitions/User"
404:
description: 不存在该用户.
default:
description: 未知错误
definitions:
User:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
更多信息可以参考，响应详情
输入和输出模型
全局的definitions允许定义通用数据结构。任何时候无论是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
在请求主体模式和响应主体模式中引用:
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
认证
在API中使用的身份验证关键词：securityDefinitions和security
securityDefinitions:
BasicAuth:
type: basic
security:
- BasicAuth: []
- 目前API支持的三种认证方法：
- 基本认证 - BasicAuth
- API密钥 - ApiKey
- OAuth2 公共流程
- securityDefinitions来定义该API支持的所有身份验证类型
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
在定义了安全机制后securityDefinitions，您可以security分别在根级别或操作级别上添加该部分，将它们应用于整个API或单个操作。
在根级别上使用时，security将指定的安全机制全局应用于所有API操作，除非在操作级别上被覆盖。在以下示例中，可以使用API密钥或OAuth 2对API调用进行身份验证.ApiKeyAuth和OAuth2名称是指上文定义过的安全机制securityDefinitions
security:
- ApiKeyAuth: []
- OAuth2: [read, write]
全局security可以在个别操作中被覆盖，从而可以使用不同的认证类型，有的根本不认证，如下例：
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.多种验证类型
security模块可使用逻辑OR和AND组合安全要求，来实现所需的结果
security: # A OR B
- A
- B
security: # A AND B
- A
B
security: # (A AND B) OR (C AND D)
- A
B
- C
D
- 使用基本身份验证或API密钥：
security:
- basicAuth: []
- apiKey: []
security:
- apiKey1: []
apiKey2: []
- API需要在请求中包含一对API密钥：
security:
- apiKey1: []
apiKey2: []
- 使用OAuth 2或一对API密钥：
security:
- oauth2: [scope1, scope2]
- apiKey1: []
apiKey2: []
