概述

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

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

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

元数据的变化

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

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

Server 定义变化

以前旧版本的长这样:

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

新版本可以长这样:

  1. [[email protected].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. [[email protected].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. [[email protected].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. [[email protected].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. [[email protected].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