更新飛機票一張 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就可以形成完整的路徑了：
<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: []

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/