概述

在写 API 文档的时候，可能你有其他选择，但是你很可能会选择或者考虑过 Swagger，但是它现在已经不叫 Swagger 了，而是捐赠给了 Linux 基金会称为了 Open API，所以本文就对比一下他们做了哪些改变。

其实从概述上看，其实 3.0 比 2.0 来说，重要的特点就是变得更抽象了，然后更加地组件化了，一张图来看是这样的：

所以下面就具体看下变化吧。

元数据的变化

所有对 swagger 的引用都被改为 openapi，这个是最直观的，第一行就需要改变。因此版本必须要有如下变化：

  1. [root@liqiang.io]# cat docs.yaml
  2. "swagger": "2.0"
  3. -->
  4. "openapi": "3.0.0"

Server 定义变化

以前旧版本的长这样：

  1. [root@liqiang.io]# cat v2-docs.yaml
  2. host: example.com
  3. basePath: /v1
  4. schemes: ['http', 'https']

新版本可以长这样：

  1. [root@liqiang.io]# cat v3-docs.yaml
  2. servers:
  3. - url: https://{subdomain}.site.com/{version}
  4.   description: The main prod server
  5.   variables:
  6.     subdomain:
  7.       default: production
  8.     version:
  9.       enum:
  10.         - v1
  11.         - v2
  12.       default: v2

请求变化

旧版本的请求无论是在 path 还是在 header 上，都是混在一起的，在 openapi 3 上将他们分开了：

  1. [root@liqiang.io]# cat v2-docs.yaml
  2. "/pets/{petId}":
  3.   post:
  4.     parameters:
  5.     - name: petId
  6.       in: path
  7.       description: ID of pet to update
  8.       required: true
  9.       type: string
  10.     - name: user
  11.       in: body
  12.       description: user to add to the system
  13.       required: true
  14.       schema:
  15.         type: array
  16.         items:
  17.           type: string

在 v3 的时候更加明确了：

  1. [root@liqiang.io]# cat v3-docs.yaml
  2. "/pets/{petId}":
  3.   post:
  4.     requestBody:
  5.       description: user to add to the system
  6.       required: true
  7.       content:
  8.         application/json: 
  9.           schema:
  10.             type: array
  11.             items:
  12.               $ref: '#/components/schemas/Pet'
  13.           examples:
  14.             - name: Fluffy
  15.               petType: Cat
  16.             - http://example.com/pet.json
  17.     parameters:
  18.       - name: petId
  19.         in: path
  20.         description: ID of pet to update
  21.         required: true
  22.         type: string

Security 变化

其实这个我还是没法直接看懂怎么用：

  1. [root@liqiang.io]# cat v2-docs.yaml
  2. securityDefinitions:
  3.   UserSecurity:
  4.     type: basic
  5.   APIKey:
  6.     type: apiKey
  7.     name: Authorization
  8.     in: header
  9. security:
  10.   - UserSecurity: []
  11.   - APIKey: []

—> 新版本：

  1. [root@liqiang.io]# cat v3-docs.yaml
  2. components:
  3.   securitySchemes:
  4.     UserSecurity:
  5.       type: http
  6.       scheme: basic
  7.     APIKey:
  8.       type: http
  9.       scheme: bearer
  10.       bearerFormat: TOKEN
  11. security:
  12.   - UserSecurity: []
  13.   - APIKey: []

Ref