重命名
swagger: 2.0
openAPI: 3.0.0

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description.
  version: 0.1.9

Swagger 2.0.png

OpenAPI 3.png

網址結構

Swagger 2.0 基礎URL結構

info:  
  title: Swagger Sample App
  host: example.com  
  basePath: /v1  
  schemes: ['http', 'https']

OpenAPI 3.0 基礎URL結構

 servers:  
 - url: https://{subdomain}.site.com/{version}
   description: The main prod server
     variables:
       subdomain:
         default: production
       version:
         enum:
           - v1
           - v2
         default: v2

我們可以定義一個基礎url，通過{}里面裝載變量值（類似于路徑模版），在使用時，通過variables屬性可以定義變量值，當然也可以給定默認值

組件

Swagger 2中的definitions概念在OpenAPI 3中標準化為【組件】，可以在多個地方重復使用且可定義，組件列表如下：

• 響應 responses （已存在）
• 參數 parameters （已存在）
• 示例 examples （新）
• 請求體 requestBodies（新）
• 標題 headers （新）
• 鏈接 links （新）
• 回調 callbacks （新）
• 模式 schemas （更新）
• 安全體系 securitySchemes（更新）

請求格式

Swagger 2

/pets/{petId}:
  post:
    parameters:
    - name: petId
      in: path
      description: ID of pet to update
      required: true
      type: string
    - name: user
      in: body
      description: user to add to the system
      required: true
      schema:
        type: array
        items:
          type: string

Swagger 2最容易混淆的方面之一是body / formData。它們是參數的子集，只能有一個或另一個，如果你使用body，格式與參數的其余部分不同（只能使用body參數，名稱不相關，格式不同，等等）

OpenAPI 3

/pets/{petId}:
  post:
    requestBody:
      description: user to add to the system
      required: true
      content:
        application/json: 
          schema:
            type: array
            items:
              $ref:     '#/components/schemas/Pet'
          examples:
            - name: Fluffy
              petType: Cat
            - http://example.com/pet.json
    parameters:
      - name: petId
        in: path
        description: ID of pet to update
        required: true
        type: string

現在，body已經被移入了它自己的叫做requestBody的部分，并且formData也已經被合并到里面。另外，cookies已經被添加為參數類型（除了現有的標題，路徑和查詢選項之外）。

requestBody有很多新的功能。現在可以提供example（或數組examples）for requestBody。這是非常靈活的（你可以傳入一個完整的例子，一個參考，甚至是一個URL的例子）。

新的requestBody支持不同的媒體類型（content是一個MIME_Types的數組，像application/json或者text/plain，當然你也可以用/捕捉所有）。

對于參數，你有兩個選擇你想如何定義它們。你可以定義一個“模式”（像原來2.0那樣），可以盡情地描述項目。如果更復雜，可以使用“requestBody”中的“content”。

響應格式

通配符的出現，我們可以以“4XX”來定義響應，而不必單獨定義每個響應碼。
響應和響應頭可以更復雜。可以使用“content”對象（如在請求中）的有效載荷。

回調概念

 myWebhook:
  '$request.body#/url':
    post:
      requestBody:
        description: Callback payload
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/SomePayload'
          responses:
            200:
              description: webhook processed!

鏈接

鏈接是OpenAPI 3最有趣的補充之一。它有點復雜，但可能非常強大。這基本上是描述“下一步是什么”的一種方式。

比方說，你得到一個用戶，它有一個addressId。這addressId本身是無用的。您可以使用鏈接來展示如何“擴大”，并獲得完整的地址。

paths:  
  /users/{userId}:
    get:
      responses:
        200:
          links:
            address:
              operationId: getAddressWithAddressId
              parameters:
                addressId: '$response.body#/addressId'

在“/ users / {userId}”的響應中，我們找回了一個addressId。“鏈接”描述了如何通過引用“$ response.body＃/ addressId”來獲取地址。

另一個用例是分頁。如果要獲取100個結果，links可以顯示如何獲得結果101-200。它是靈活的，這意味著它可以處理任何分頁方案limits來cursors。

安全

Swagger 2

securityDefinitions:  
  UserSecurity:
    type: basic
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:  
  - UserSecurity: []
  - APIKey: []

OpeanAPI 3

components:  
  securitySchemes:
    UserSecurity:
      type: http
      scheme: basic
    APIKey:
      type: http
      scheme: bearer
      bearerFormat: TOKEN
security:  
  - UserSecurity: []
  - APIKey: []

一堆安全性的變化！它已被重命名，OAuth2流名已更新，您可以有多個流，并且支持OpenID Connect。“基本”類型已被重命名為“http”，現在安全可以有一個“方案”和“bearerFormat”。

飛機票至Swagger 2

參考：

https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument

建議閱讀：

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject