Swagger 2与OpenAPI 3

重命名
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与OpenAPI 3》 Swagger 2.0.png

《Swagger 2与OpenAPI 3》 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

    原文作者:miku设定
    原文地址: https://www.jianshu.com/p/879baf1cff07
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞