Swagger2与OpenAPI3

重命名
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