Swagger2.0结构说明

更新飞机票一张 Swagger 2 与 OpenAPI 3

---

元数据

1. 每个Swagger规范都以Swagger版本开始

swagger: "2.0"

2. 需要指定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就可以形成完整的路径了：
:////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: []

1. 目前API支持的三种认证方法：

• 基本认证 - BasicAuth
• API密钥 - ApiKey
• OAuth2 公共流程

2. 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: []

---

参考资料：
https://swagger.io/docs/specification/about/