重命名
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
網(wǎng)址結(jié)構(gòu)
Swagger 2.0 基礎(chǔ)URL結(jié)構(gòu)
info:
title: Swagger Sample App
host: example.com
basePath: /v1
schemes: ['http', 'https']
OpenAPI 3.0 基礎(chǔ)URL結(jié)構(gòu)
servers:
- url: https://{subdomain}.site.com/{version}
description: The main prod server
variables:
subdomain:
default: production
version:
enum:
- v1
- v2
default: v2
我們可以定義一個基礎(chǔ)url，通過{}里面裝載變量值（類似于路徑模版），在使用時，通過variables屬性可以定義變量值，當(dāng)然也可以給定默認(rèn)值
組件
Swagger 2中的definitions概念在OpenAPI 3中標(biāo)準(zhǔn)化為【組件】，可以在多個地方重復(fù)使用且可定義，組件列表如下：
- 響應(yīng) responses （已存在）
- 參數(shù) parameters （已存在）
- 示例 examples （新）
- 請求體 requestBodies（新）
- 標(biāo)題 headers （新）
- 鏈接 links （新）
- 回調(diào) 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。它們是參數(shù)的子集，只能有一個或另一個，如果你使用body，格式與參數(shù)的其余部分不同（只能使用body參數(shù)，名稱不相關(guān)，格式不同，等等）
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
現(xiàn)在，body已經(jīng)被移入了它自己的叫做requestBody的部分，并且formData也已經(jīng)被合并到里面。另外，cookies已經(jīng)被添加為參數(shù)類型（除了現(xiàn)有的標(biāo)題，路徑和查詢選項之外）。
requestBody有很多新的功能。現(xiàn)在可以提供example（或數(shù)組examples）for requestBody。這是非常靈活的（你可以傳入一個完整的例子，一個參考，甚至是一個URL的例子）。
新的requestBody支持不同的媒體類型（content是一個MIME_Types的數(shù)組，像application/json或者text/plain，當(dāng)然你也可以用/捕捉所有）。
對于參數(shù)，你有兩個選擇你想如何定義它們。你可以定義一個“模式”（像原來2.0那樣），可以盡情地描述項目。如果更復(fù)雜，可以使用“requestBody”中的“content”。
響應(yīng)格式
通配符的出現(xiàn)，我們可以以“4XX”來定義響應(yīng)，而不必單獨定義每個響應(yīng)碼。
響應(yīng)和響應(yīng)頭可以更復(fù)雜。可以使用“content”對象（如在請求中）的有效載荷。
回調(diào)概念
myWebhook:
'$request.body#/url':
post:
requestBody:
description: Callback payload
content:
'application/json':
schema:
$ref: '#/components/schemas/SomePayload'
responses:
200:
description: webhook processed!
鏈接
鏈接是OpenAPI 3最有趣的補(bǔ)充之一。它有點復(fù)雜，但可能非常強(qiáng)大。這基本上是描述“下一步是什么”的一種方式。
比方說，你得到一個用戶，它有一個addressId。這addressId本身是無用的。您可以使用鏈接來展示如何“擴(kuò)大”，并獲得完整的地址。
paths:
/users/{userId}:
get:
responses:
200:
links:
address:
operationId: getAddressWithAddressId
parameters:
addressId: '$response.body#/addressId'
在“/ users / {userId}”的響應(yīng)中，我們找回了一個addressId。“鏈接”描述了如何通過引用“$ response.body＃/ addressId”來獲取地址。
另一個用例是分頁。如果要獲取100個結(jié)果，links可以顯示如何獲得結(jié)果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”，現(xiàn)在安全可以有一個“方案”和“bearerFormat”。
飛機(jī)票至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
