Table of Contents Introduction First Chapter

Transcription

1 Table of Contents First Chapter

2 如何编写基于 OpenAPI 规范的 API 文档 [TOC] 前言编写目的 本文介绍如何使用 Swagger 编写 API 文档 通过阅读本文, 你可以 : 了解 swagger 是什么掌握使用 swagger 编写 API 文档的基本方法 涉及范围 本文包括对 swagger specification( 以下译作 规范 ) 的介绍, 如何使用 swaager 协议编写出功能完整 结构清晰的 API 文档, 以及项目实践中需要注意的问题 swagger 的生态完整, 从文档生成 编辑 测试到各种语言的代码自动生成, 都有很多开源工具支持 本文中不介绍这些工具的使用 第 1 章简介 1.1 Swagger 2

3 The World's Most Popular Framework for APIs. Starting January 1st 2016 the Swagger Specification has been donated( 捐赠 ) to the Open API Initiative (OAI) and is the foundation of the OpenAPI Specification. Swagger( 丝袜哥 ) 给人第一印象就是 最 (hen) 流 (niu) 行 (bai), 不懂 Swagger 咱就 out 了 它的官方网站是 Swagger 是一个简单但功能强大的 API 表达工具 它具有地球上最大的 API 工具生态系统, 数以千计的开发人员, 使用几乎所有的现代编程语言, 都在支持和使用 Swagger 使用 Swagger 生成 API, 我们可以得到交互式文档, 自动生成代码的 SDK 以及 API 的发现特性等 现在,Swagger 已经帮助包括 Apigee, Getty 图像, Intuit, LivingSocial, McKesson, 微软, Morningstar 和 PayPal 等世界知名企业建立起了一套基于 RESTful API 的完美服务系统 2.0 版本已经发布,Swagger 变得更加强大 值得感激的是,Swagger 的源码 100% 开源在 github 1.2 OpenAPI 规范 OpenAPI 规范是 Linux 基金会的一个项目, 试图通过定义一种用来描述 API 格式或 API 定义的语言, 来规范 RESTful 服务开发过程 OpenAPI 规范帮助我们描述一个 API 的基本信息, 比如 : 有关该 API 的一般性描述可用路径 (/ 资源 ) 在每个路径上的可用操作 ( 获取 / 提交...) 每个操作的输入 / 输出格式目前 V2.0 版本的 OpenAPI 规范 ( 也就是 SwaggerV2.0 规范 ) 已经发布并开源在 github 上 该文档写的非常好, 结构清晰, 方便随时查阅 关于规范的学习和理解, 本文最后还有个彩蛋 1.3 为啥要使用 OpenAPI 规范? OpenAPI 规范这类 API 定义语言能够帮助你更简单 快速的表述 API, 尤其是在 3

4 API 的设计阶段作用特别突出根据 OpenAPI 规范编写的二进制文本文件, 能够像代码一样用任何 VCS 工具管理起来一旦编写完成,API 文档可以作为 : 需求和系统特性描述的根据前后台查询 讨论 自测的基础部分或者全部代码自动生成的根据其他重要的作用, 比如开放平台开发者的手册 如何编写 API 文档? 语言 :JSON vs YAML 我们可以选择使用 JSON 或者 YAML 的语言格式来编写 API 文档 但是个人建议使用 YAML 来写, 原因是它更简单 一图胜千言, 先看用 JSON 写的文档 : { "swagger": "2.0", "info": { "version": "1.0.0", "title": "Simple API", "description": "A simple API to learn how to write OpenA PI Specification" }, "schemes": [ "https" ], "host": "simple.api", "basepath": "/openapi101", "paths": { "/persons": { "get": { "summary": "Gets some persons", "description": "Returns a list containing all pe rsons.", "responses": { "200": { "description": "A list of Person", 4

5 } } } } } } "schema": { "type": "array", "items": { "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "username": { "type": "string" } } } } 再来看看同一份 API 文档的 YAML 实现 : 5

6 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. 200: description: A list of Person type: array items: required: - username properties: firstname: lastname: username: 对于普通人来说, 似乎用 YAML 更能够简化书写和阅读 这里我们并没有非此即彼的选择问题, 因为 : 几乎所用支持 OpenAPI 规范的工具都支持 YAML 有很多的工具可以实现 YAML-JSON 之间的转换 6

7 所以, 用自己喜欢的方式书写即可 ( 后面的示例文档也都是用 YAML 来写的 强烈推荐使用 YAML ) 编辑器 编写 API 文档, 其实我们只是在写一个简单的文本文件 我们可以用任何最普通的文档编辑器来写 但是为了提高效率, 还是建议使用专业的编辑工具 众多工具中, 最好的选择是 Swagger Editor, 它能够提供语法高亮 自动完成 即时预览等功能, 非常强大 左边编辑 API 文档, 右边实时预览 下面这张动图展示编辑提升功能 : 7

8 我们可以使用在线版本来编辑, 也可以非常简单的本地部署, 更多细节请参考另一 篇文档 Swagger 环境搭建.md 以及 Swagger Editor 开源仓库上的说明 第 2 章从零开始 这一章主要介绍 API 的基本组成部分, 包括提供给 API 消费者 ( 所有可能访问 API 的 个体, 下简称 消费者 ) 的的不同 HTTP 请求方法 路径, 请求和消息体中的参数, 以及返回给消费者的不同 HTTP 状态及响应消息体 2.1 最简单的例子 我们从一个最简单 ( 几乎没有东西 ) 的 API 文档开始 : 8

9 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: {} 这个文档的内容分成四部分, 下面分别来说明 OpenAPI 规范的版本号 首先我们要通过一个 swagger 属性来声明 OpenAPI 规范的版本 swagger: "2.0" 你没看错, 是 swagger, 上面已经介绍了,OpenAPI 规范是基于 Swagger 的, 在 未来的版本中, 这个属性可能会换成别的 目前这个属性的值, 暂时只能填写 为 API 描述信息 然后我们需要说明一下 API 文档的相关信息, 比如 API 文档版本 ( 注意不同于上面的 规范版本 ) API 文档名称已经可选的描述信息 info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication 9

10 2.1.3 API 的 URL 作为 web API, 一个很重要的信息就是用来给消费者使用的根 URL, 可以用协议 (http 或者 https) 主机名 根路径来描述 : schemes: - https host: simple.api basepath: /openapi101 这这个例子中, 消费者把 作为根节点来访问各种 API 因为和具体环境有关, 不涉及 API 描述的根本内容, 所以这部分信息是可选 的 API 的操作 (operation) 这个例子中, 我们没有写 API 的操作, 用一个 YAML 的空对象 {} 先占个位置 2.2 定义一个 API 操作 如果我们要展示一组用户信息, 可以这样描述 : 10

11 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. 200: description: A list of Person type: array items: required: - username properties: firstname: lastname: username: 添加一个路径 (path) 我们添加一个 /persons 的路径, 用来访问一组用户信息 : 11

12 paths: /persons: 在路径中添加一个 HTTP 方法 在每个路径中, 我们可以添加任意的 HTTP 动词来操作所需要的资源 比如需要展示一组用户信息, 我们可以在 /persons 路径中添加 get 方法, 同时还可以填写一些简单的描述信息 (summary) 或者说明该方法的一段长篇大论 (description) get: summary: Gets some persons description: Returns a list containing all persons. 这样一来, 我们调 get 方法就能获取一个用户 信息列表了 定义响应 (response) 类型 对于每个方法 ( 或操作 ), 我们都可以在响应 (responses) 中添加任意的 HTTP 状态码 ( 比如 200 OK 或者 404 Not Found 等 ) 这个例子中我们添加上 200 的响应 : 200: description: A list of Person 定义响应内容 get /persons 这个接口返回一组用户信息, 我们通过响应消息中的模式 (schema) 属性来描述清楚具体的返回内容 一组用户信息就是一个用户信息对象的数组 (array), 每一个数组元素则是一个用户信息对象 (object), 该对象包含三个 string 类型的属性 : 姓氏 名字 用户名, 其中用户名必须提供 (required) 12

13 type: array items: required: - username properties: firstname: lastname: username: 2.3 定义请求参数 (query parameters) 用户太多, 我们不想一股脑全部输出出来 这个时候, 分页输出是个不错的选择, 我们可以通过添加请求参数来实现 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. 13

14 - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer # END #### 200: description: A list of Person type: array items: required: - username properties: firstname: lastname: username: 在 get 方法中增加请求参数 首先我们在 get 方法中增加一个参数属性 : 14

15 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. # END #### 添加分页参数 在参数列表中, 我们添加两个名字 (name) 分别叫 做 pagesize 和 pagenumber 的整型 (integer) 参数, 并作简单描述 : - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer # END #### ## 这样一来, 消费者就可以通过 get /persons?pagesize=20&pagenumber=2 来访问 第 2 页的用户信息 ( 不超过 20 条 ) 了 2.4 定义路径参数 (path parameter) 15

16 有时候我们想要根据用户名来查找用户信息, 这时我们需要增加一个接口操作, 比 如可以添加一个类似 /persons/{username} 的操作来获取用户信息 注 意,{username} 是在请求路径中的参数 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A list of Person type: array items: required: - username 16

17 properties: firstname: lastname: username: /persons/{username}: get: summary: Gets a person description: Returns a single person for its username - name: username in: path required: true description: The person's username 200: description: A Person required: - username properties: firstname: lastname: username: 404: description: The Person does not exists. # END #### 添加一个 get /persons/{username} 操作 17

18 首先我们在 /persons 路径后面, 增加一个 /persons/{username} 的路径, 并定义一 个 get ( 操作 ) 方法 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: username: /persons/{username}: get: summary: Gets a person description: Returns a single person for its username # END #### 定义路径参数 username 因为 {username} 是路径参数, 我们需要先像请求参数一样将它添加到 parameters 属性中, 注意名称应该同上面大括号 ( { } ) 里面的名称一致 并通过 in 这个属性, 来表示它是一个路径 (path) 参数 18

19 - name: username in: path required: true description: The person's username 定义路径参数时很容易出现的问题就是忘记 : required: true,swagger 的自动完成功能中没有包含这个属性定义 如果没有写 require 属性, 默认值是 false, 也就是说 username 参数时可选的 可事实上, 作为路径参数, 它是必需的 定义响应消息 别忘了获取单个用户信息也需要填写 200 响应消息, 响应消息体的内容就是之前描 述过的用户信息 ( 用户信息列表中的一个元素 ): 200: description: A Person required: - username properties: firstname: lastname: username: 当然,API 的提供者会对 username 进行校验, 如果查无此人, 应该返回 404 的异 常状态 所以我们再加上 404 状态的响应 : 404: description: The Person does not exists. 19

20 2.5 定义消息体参数 (body parameter) 当我们需要添加一个用户信息时, 我们需要一个能够提供 post /persons 的 API 操 作 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A list of Person type: array items: required: 20

21 - username properties: firstname: lastname: username: post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. required: - username properties: firstname: lastname: username: 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. # END #### /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username 21

22 in: path required: true description: The person's username 200: description: A Person required: - username properties: firstname: lastname: username: 404: description: The Person does not exists 添加一个 post /persons 操作 首先在 /persons 路径下廷加一个 post 操作 : paths: /persons: post: summary: Creates a person description: Adds a new person to the persons list 定义消息体参数 接下来我们给 post 方法添加参数, 通过 in 属性显式说明参数是在 body 中的 参数的定义参考 get /persons/{username} 的 200 响应消息体参数, 也就是包含用户的姓氏 名字 用户名 22

23 - name: person in: body description: The person to create. required: - username properties: firstname: lastname: username: 定义响应消息 最后不要忘记定义 post 操作的响应消息 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. 第 3 章文档瘦身 现在我们已经学会了编写 API 文档的基本方法 不过上面的例子中存在一些重复, 这对于程序员的嗅觉来说, 就是代码的 坏味道 这一章我们一起学习如何通过抽取可重用的定义 (definitions) 来简化 API 文档 3.1 简化数据模型 我们认真观察第 2 章最后输出的 API 文档, 很容易发现 Person 的定义出现了三次, 非常的不 DRY 23

24 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A list of Person type: array items: #START 第 1 次定义 ############# required: - username properties: 24

25 firstname: lastname: username: # END 第 1 次定义 ############# post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. #START 第 2 次定义 ############# required: - username properties: firstname: lastname: username: # END 第 2 次定义 ############# 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username 25

26 in: path required: true description: The person's username 200: description: A Person #START 第 3 次定义 ############# required: - username properties: firstname: lastname: username: # END 第 3 次定义 ############# 404: description: The Person does not exists. 现在, 我们通过可重用的定义 (definition) 来重构这个文档 : swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 26

27 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A list of Person $ref: "#/definitions/persons" # END #### post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. $ref: "#/definitions/person" # END #### 204: description: Persons succesfully created. 27

28 400: description: Persons couldn't have been created. /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username in: path required: true description: The person's username 200: description: A Person $ref: "#/definitions/person" # END #### 404: description: The Person does not exists. #START 新增定义 ############## definitions: Person: required: - username properties: firstname: lastname: username: Persons: type: array items: 28

29 $ref: "#/definitions/person" # END 新增定义 ############### ################# 文档简化了很多 这得益于 OpenAPI 规范中关于定义 (definition) 的章节中允许我 们 一处定义, 处处使用 添加定义 (definitions) 项 我们首先在 API 文档的尾部添加一个定义 (definitions) 项 ( 其实它也可以放在文 档的任意位置, 只不过大家习惯放在文档末尾 ): 404: description: The Person does not exists. definitions: # END #### 增加一个可重用的 ( 对象 ) 定义 然后我们增加一个 Person 对象的定义 : 29

30 definitions: Person: required: - username properties: firstname: lastname: username: # END #### 引用一个定义来增加另一个定义 在定义项中, 我们可以立即引用刚才定义好的 Person 来增加另一个定义,Persons Persons 是一个 Person 对象的数组 与之前直接定义的不同之处是, 我们增加了一个引用 (reference) 属性, 也就是 $ref 来引用 Person Persons: type: array items: $ref: "#/definitions/person" 在响应消息中使用定义 一旦定义好了 Person, 我们可以把原来在响应消息中相应的定义字段替换掉 get/persons 原来 : 30

31 200: description: A list of Person type: array items: required: - username properties: firstname: lastname: 现在 : 200: description: A list of Person $ref: "#/definitions/persons" get/persons/{username} 原来 : 31

32 200: description: A Person required: - username properties: firstname: lastname: username: 现在 : 200: description: A Person $ref: "#/definitions/person" 在参数中使用定义 不仅仅在消息中可以使用定义, 在参数中也可以使用 post /persons 原来 : 32

33 post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. required: - username properties: firstname: lastname: username: 现在 : post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. $ref: "#/definitions/person" 3.2 简化响应消息 我们看到了引用 ($ref) 的作用, 接下来我们再把它用到响应消息的定义中 : swagger: "2.0" info: 33

34 version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A list of Person $ref: "#/definitions/persons" 500: $ref: "#/responses/standard500errorresponse" # END #### post: summary: Creates a person description: Adds a new person to the persons list. 34

35 - name: person in: body description: The person to create. $ref: "#/definitions/person" 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. 500: $ref: "#/responses/standard500errorresponse" # END #### /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username in: path required: true description: The person's username 200: description: A Person $ref: "#/definitions/person" 404: description: The Person does not exists. 500: $ref: "#/responses/standard500errorresponse" # END #### 35

36 definitions: Person: required: - username properties: firstname: lastname: username: Persons: type: array items: $ref: "#/definitions/person" Error: properties: code: message: Standard500ErrorResponse: description: An unexpected error occured. $ref: "#/definitions/error" # END #### 定义可重用的 HTTP 500 响应 发生 HTTP 500 错误时, 假如我们希望每一个 API 操作都返回一个带有错误码 (error code) 和描述信息 (message) 的响应, 我们可以这样做 : paths: 36

37 /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A list of Person $ref: "#/definitions/persons" 500: description: An unexpected error occured. properties: code: message: # END #### post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. $ref: "#/definitions/person" 37

38 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. 500: description: An unexpected error occured. properties: code: message: # END #### /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username in: path required: true description: The person's username 200: description: A Person $ref: "#/definitions/person" 404: description: The Person does not exists. 500: description: An unexpected error occured. 38

39 properties: code: message: # END #### 增加一个 Error 定义 按照 一处定义 处处引用 的原则, 我们可以在定义项中增加 Error 的定义 : definitions: Person: required: - username properties: firstname: lastname: username: Persons: type: array items: $ref: "#/definitions/person" Error: properties: code: message: # END #### 而且我们也学会了使用引用 ($ref), 所以我们可以这样写 : 39

40 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A list of Person $ref: "#/definitions/persons" 500: description: An unexpected error occured. $ref: "#/definitions/error" # END #### post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. $ref: "#/definitions/person" 204: 40

41 description: Persons succesfully created. 400: description: Persons couldn't have been created. 500: description: An unexpected error occured. $ref: "#/definitions/error" # END #### /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username in: path required: true description: The person's username 200: description: A Person $ref: "#/definitions/person" 404: description: The Person does not exists. 500: description: An unexpected error occured. $ref: "#/definitions/error" # END #### 定义一个可重用的响应消息 41

42 上面的文档中, 还是有一些重复的内容 我们可以根据 OpenAPI 规范中的 responses 章节的描述, 通过定义一个可重用的响应消息, 来进一步简化文档 definitions: Person: required: - username properties: firstname: lastname: username: Persons: type: array items: $ref: "#/definitions/person" Error: properties: code: message: Standard500ErrorResponse: description: An unexpected error occured. $ref: "#/definitions/error" # END #### 注意 : 响应消息中引用了 Error 的定义 使用已定义的响应消息 我们还是通过引用 ($ref) 来使用一个已经定义好的响应消息, 比如 : 42

43 get /users 200: description: A list of Person $ref: "#/definitions/persons" 500: $ref: "#/responses/standard500errorresponse" # END #### post/users 204: description: Persons succesfully created. 400: description: Persons couldn't have been created. 500: $ref: "#/responses/standard500errorresponse" # END #### get/users/{username} 43

44 200: description: A Person $ref: "#/definitions/person" 404: description: The Person does not exists. 500: $ref: "#/responses/standard500errorresponse" # END #### 3.3 简化参数定义 类似数据模型 响应消息的简化, 参数定义的简化也很容易 swagger: "2.0" info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specif ication schemes: - https host: simple.api basepath: /openapi101 paths: /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. 44

45 - $ref: "#/parameters/pagesize" - $ref: "#/parameters/pagenumber" # END #### 200: description: A list of Person $ref: "#/definitions/persons" 500: $ref: "#/responses/standard500errorresponse" post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body description: The person to create. $ref: "#/definitions/person" 204: description: Person succesfully created. 400: description: Person couldn't have been created. 500: $ref: "#/responses/standard500errorresponse" /persons/{username}: - $ref: "#/parameters/username" # END #### get: summary: Gets a person description: Returns a single person for its username. 45

46 200: description: A Person $ref: "#/definitions/person" 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" delete: summary: Deletes a person description: Delete a single person identified via its use rname 204: description: Person successfully deleted. 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" /persons/{username}/friends: - $ref: "#/parameters/username" # END #### get: summary: Gets a person's friends description: Returns a list containing all persons. The li st supports paging. - $ref: "#/parameters/pagesize" - $ref: "#/parameters/pagenumber" # END #### 46

47 200: description: A person's friends list $ref: "#/definitions/persons" 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" definitions: Person: required: - username properties: firstname: lastname: username: Persons: type: array items: $ref: "#/definitions/person" Error: required: - code - message properties: code: message: Standard500ErrorResponse: description: An unexpected error occured. $ref: "#/definitions/error" PersonDoesNotExistResponse: 47

48 description: Person does not exist. username: name: username in: path required: true description: The person's username pagesize: name: pagesize in: query description: Number of persons returned type: integer pagenumber: name: pagenumber in: query description: Page number type: integer # END #### 路径参数只定义一次 如果我们现在想要删除一个用户的信息, 就需要增加一个 delete /persons/{username} 的操作, 可以这样 : /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username in: path required: true 48

49 description: The person's username # END #### 200: description: A Person $ref: "#/definitions/person" 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" delete: summary: Deletes a person description: Delete a single person identified via its use rname - name: username in: path required: true description: The person's username # END #### 204: description: Person successfully deleted. 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" 但是上面两次对参数 username 的定义, 却让人有点难受 好消息是我们可以定 义路径级别的参数 ( 之前都是定义在操作级别 ) 49

50 /persons/{username}: - name: username in: path required: true description: The person's username # END #### get: summary: Gets a person description: Returns a single person for its username. 200: description: A Person $ref: "#/definitions/person" 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" delete: summary: Deletes a person description: Delete a single person identified via its use rname 204: description: Person successfully deleted. 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" 定义可重用的参数 50

51 如果我们想根据用户名查找该用户的朋友圈, 可以添加一个 get /persons/{username}/friends 的操作 根据前面所学的内容, 第一反应应该这样 写 : /persons/{username}/friends: - name: username in: path required: true description: The person's username get: summary: Gets a person's friends description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer 200: description: A person's friends list $ref: "#/definitions/persons" 404: $ref: "#/responses/persondoesnotexistresponse" 500: $ref: "#/responses/standard500errorresponse" 可以看到, 关于 username pagesize pagenumber 的定义跟前面的 /person/{username} get /persons 中的定义重复 如何消除重复呢? 定义可重用的参数 51

52 根据 3.1 和 3.2 中的内容, 我们可以参考 OpenAPI 规范, 融汇贯通 username: name: username in: path required: true description: The person's username pagesize: name: pagesize in: query description: Number of persons returned type: integer pagenumber: name: pagenumber in: query description: Page number type: integer 使用定义参数 借助万能的引用 ($ref), 这都是小菜一碟 比如 : get /persons 原来 : 52

53 /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer # END #### 现在 : /persons: get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. - $ref: "#/parameters/pagesize" - $ref: "#/parameters/pagenumber" # END #### get 和 delete /persons/{username} 原来 : 53

54 /persons/{username}: - name: username in: path required: true description: The person's username # END #### 现在 : /persons/{username}: - $ref: "#/parameters/username" # END #### get /persons/{username}/friends 原来 : 54

55 /persons/{username}/friends: - name: username in: path required: true description: The person's username # END #### get: summary: Gets a person's friends description: Returns a list containing all persons. The li st supports paging. - name: pagesize in: query description: Number of persons returned type: integer - name: pagenumber in: query description: Page number type: integer # END #### 现在 : 55

56 /persons/{username}/friends: - $ref: "#/parameters/username" # END #### get: summary: Gets a person's friends description: Returns a list containing all persons. The li st supports paging. - $ref: "#/parameters/pagesize" - $ref: "#/parameters/pagenumber" # END #### 第 4 章深入了解一下 通过前面的练习, 我们可以写出一篇结构清晰 内容精炼的 API 文档了 可是 OpenAPI 规范还给我们提供了更多的便利和惊喜, 等着我们去了解和掌握 这一章主要介绍用于定义属性和数据模型的高级方法 4.1 私人定制 Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. Models are described using the Schema Object which is a subset of JSON Schema Draft 4. OpenAPI Specification Data Types 使用 JSON Schema Draft 4, 我们可以定义任意类型的各种属性, 举例说明 字符串 (Strings) 长度和格式 56

57 当定义个字符串属性时, 我们可以定制它的长度及格式 : 属性 类型 描述 minlength number 字符串最小长度 maxlength number 字符串最大长度 pattern string 正则表达式 ( 如果你暂时还不熟悉正则表达式, 可以看看 Regex 101) 如果我们规定用户名是长度介于 8~64, 而且只能由小写字母和数字来构成, 那么我 们可以这样写 : username: pattern: "[a-z0-9]{8,64}" minlength: 8 maxlength: 日期和时间 日期和时间的处理参考 RFC 3339, 我们唯一要做的就是写对格式 : 格式 属性包含内容 属性示例 date ISO8601 full-date datetime ISO8601 date-time T16:06:05Z 如果我们在 Person 的定义中增加生日和上次登录时间时间戳, 我们可以这样 写 : dateofbirth: format: date lasttimeonline: format: datetime 如果想深入掌握 API 中处理日期和时间的方法, 我们应该继续阅读 Jason Harmon 写的文章 5 laws of API dates and times 57

58 4.1.3 数字类型和范围 当我们定义一个数字类型的属性时, 我们可以规定它是一个整型 长型 浮点型或 者双浮点型 名称 类型 格式 integer integer int32 long integer int64 float number float double number double 和字符串一样, 我们也可以定义数字属性的范围, 比如 : 属性 类型 描述 minimum number 最小值 maximum number 最大值 exclusiveminimum boolean 数值必须 > 最小值 exclusivemaximum boolean 数值必须 < 最大值 multipleof number 数值必须是 multipleof 的整数倍 如果我们规定 pagesize 必须是整数, 必须 > 0 且 <=100, 还必须是 10 的整数 倍, 可以这样写 : pagesize: name: pagesize in: query description: Number of persons returned type: integer format: int32 minimum: 0 exclusiveminimum: true maximum: 100 exclusivemaximum: false multipleof: 枚举类型 58

59 我们还可以定义枚举类型, 比如定义 Error 时, 我们可以这样写 : code: enum: - DBERR - NTERR - UNERR code 的值只能从三个枚举值中选择 数值的大小和唯一性 数字的大小和唯一性通过下面这些属性来定义 : 属性 类型 描述 minitems number 数值中的最小元素个数 maxitem number 数值中的最大元素个数 uniqueitems boolean 标示数组中的元素是否唯一 比如我们定义一个用户数组 Persons, 希望返回的用户信息条数介于 10~100 之间, 而且不能有重复的用户信息, 我们可以这样写 : Persons: properties: items: type: array minitems: 10 maxitems: 100 uniqueitems: true items: $ref: "#/definitions/person" 二进制数据 可以用 string 类型来表示二进制数据 : 59

60 格式 属性包含 byte binary Base64 编码字符 任意十进制的数据序列 比如我们需要在用户信息中增加一个头像属性 (avatarbase64png) 用 base64 编 码的 PNG 图片来表示, 可以这样写 : avatarbase64png: format: byte 4.2 高级数据定义 读写操作同一定义的数据 有时候我们读取资源信息的内容会比我们写入资源信息的内容 ( 属性 ) 更多, 这很常见 是不是意味着我们必须专门为读取资源和写入资源分别定义不同的数据模型呢? 幸运的是,OpenAPI 规范中提供了 readonly 字段来帮我们解决整问题 比如 : lasttimeonline: format: datetime readonly: true 上面这个例子中, 上次在线时间 (lasttimeonline ) 是 Person 的一个属性, 我们 获取用户信息时需要这个属性 但是很明显, 在创建用户时, 我们不能把这个属性 post 到服务器 于是我们可以把它标记为 readonly 组合定义确保一致性 一致性设计是在编写 API 文档时需要重点考虑的问题 比如我们在获取一组用户信息时, 需要同时获取页面信息 ( totalitems, totalpage, pagesize, currentpage) 等, 而且这些信息必须在根节点上 60

61 怎么办呢? 首先想到的做法就是 : PagedPersonsV1: properties: items: type: array items: $ref: "#/definitions/person" totalitems: type: integer totalpages: type: integer pagesize: type: integer currentpage: type: integer 如果其他 API 操作也需要这些页面信息, 那就意味着这些属性必须一遍又一遍的定义 不仅重复体力劳动, 而且还很危险 : 比如忘记了其中的一两个属性, 或者需要添加一个新的属性进来, 那就是霰弹式的修改, 想想都很悲壮 稍微好一点的做法, 就是根据前面学习的内容, 把这几个属性抽取出来, 建立一个 Paging 模型, 一处定义 处处使用 : 61

62 PagedPersonsV2: properties: items: type: array items: $ref: "#/definitions/person" paging: $ref: "#/definitions/paging" Paging: properties: totalitems: type: integer totalpages: type: integer pagesize: type: integer currentpage: type: integer 但是, 页面属性都不再位于根节点! 与我们前面设定的要求不一样了 怎么破? JSON Schema v4 property 中定义的 allof, 能帮我们解围 : PagedPersons: allof: - $ref: "#/definitions/persons" - $ref: "#/definitions/paging" 上面这个例子表示,PagedPersons 根节点下, 具有将 Persons 和 Paging 展开后 的全部属性 allof 同样可以使用行内的数据定义, 比如 : 62

63 PagedCollectingItems: allof: - properties: items: type: array minitems: 10 maxitems: 100 uniqueitems: true items: $ref: "#/definitions/collectingitem" - $ref: "#/definitions/paging" 数据模型的继承 (TODO) 目前各工具支持程度不高, 待续 第 5 章输入输出模型 这一章主要介绍如何定义高度精确化的参数和响应消息等 5.1 高级参数定义 必带参数和可选参数 我们已经知道使用关键字 required 来定义一个必带参数 定义必带参数和可选参数 在一个参数中, required 是一个 boolean 型的可选值 它的默认值是 false 比如在某个操作中,username 是必填参数 : 63

64 username: name: username in: path required: true # END #### description: The person's username 定义必带属性和可选属性根据定义, required 是一个字符串列表, 列表中包含各必带参数名 如果某个参数在这张列表中找不到, 那就说明它不是必带参数 如果没有定义 required, 就说明所有参数都是可选 如果 required 定义在一个 HTTP 请求上, 这说明所有的请求参数都是必填 在 POST persons 中有 Person 的定义, 在这里 username 这个属性是必带的, 我们可以指定它为 required, 其他非必带字段则不指定 : 64

65 Person: required: - username # END #### properties: firstname: lastname: username: pattern: '[a-z0-9]{8,64}' minlength: 8 maxlength: 64 dateofbirth: format: date lasttimeonline: format: date-time readonly: true avatarbase64png: format: byte default: data:image/png;base64,i spokenlanguages: $ref: '#/definitions/spokenlanguages' 带默认值的参数 通过关键字 default, 我们可以定义一个参数的默认值 当这个参数不可得 ( 请求未带或者服务器未返回 ) 时, 这个参数就取默认值 因此设定了某个参数的默认值后, 它是否 required 就没意义了 定义参数的默认值 65

66 我们定义参数 pagesize 的默认值为 20, 那么如果请求时没有填写 pagesize, 服 务器也会默认返回 20 个元素 pagesize: name: pagesize in: query description: Number of persons returned type: integer format: int32 minimum: 0 exclusiveminimum: true maximum: 100 exclusivemaximum: false multipleof: 10 default: 20 # END #### 定义属性的默认值 我们在定义 Person 对象时, 希望给每个用户一个默认头像, 也就是要给 avatarbase64png 属性一个默认值 默认头像 : 66

67 Person: required: - username properties: firstname: lastname: username: pattern: '[a-z0-9]{8,64}' minlength: 8 maxlength: 64 dateofbirth: format: date lasttimeonline: format: date-time readonly: true avatarbase64png: format: byte default: data:image/png;base64,ivborw0kggoaaaansuheuga rkjggg== # END #### spokenlanguages: $ref: '#/definitions/spokenlanguages' 带空值的参数 在 GET /persons 时, 如果我们想添加一个参数来过滤 是否通过实名认证 的用户, 应该怎么做呢? 首先想到的是这样 :GET /persons? page=2&includeverifiedusers=true, 问题是 includeverifiedusers 语义已经如此 67

68 清晰, 而让 =true 显得很多余 我们能不能直接用 :GET /persons? page=2&includeverifiedusers 呢? 要做到这种写法, 我们需要一个关键字 allowemptyvalue 我们定义 includeverifiedusers 时允许它为空 那么如果我们请求 GET /persons? page=2&includeverifiedusers 则表示需要过滤 实名认证 用户, 如果我们直接请求 GET /persons?page=2 则表示不过滤 : includenonverifiedusers: name: includenonverifiedusers in: query type: boolean default: false allowemptyvalue: true # END #### 参数组 设计 API 的时候, 我们经常会遇到在 GET 请求中需要携带一组请求参数的情况 如何在 API 文档章呈现呢? 很简单, 我们只需要设定参数类型 (type) 为 array, 并选择合适的组合格式 (collectionformat) 就行了 COLLECTIONFORMAT csv (default value) ssv tsv 描述 Comma separated values( 逗号分隔 ) foo,bar Space separated values( 空格分隔 ) foo bar Tab separated values( 反斜杠分隔 ) foo\tbar pipes Pipes separated values( 竖线分隔 ) `foo\ bar` multi 单属性可以取多个值, 比如 foo=bar&foo=baz. 只适用于查询参数和表单参数 68

69 比如我们想根据多种参数 (username, firstname, lastname, lasttimeonline ) 等来对 Person 进行带排序的查询 我们需要一个这样的 API 请求 : GET /persons?sort=-lasttimeonline +firtname +lastname 用于排序的参数是 sort, + 表示升序, - 表示降序 相应的 API 文档, 可以这样写 : sortpersons: name: sort in: query type: array uniqueitems: true minitems: 1 maxitems: 3 collectionformat: pipes items: pattern: '[-+](username lasttimeonline firstname lastname)' 现在我们就能搞定 GET /persons?sort=-lasttimeonline +firtname +lastname 这种 请求了 当然, 我们还可以指定排序的默认值, 锦上添花 69

70 sortpersons: name: sort in: query type: array uniqueitems: true minitems: 1 maxitems: 3 collectionformat: pipes items: pattern: '[-+](username lasttimeonline firstname lastname)' default: - -lasttimeonline - +username # END #### 消息头 (Header) 参数 参数, 按照位置来分, 不仅仅包含路径参数 请求参数和消息体参数, 还包括消息头参数和表单参数等 比如我们可以在 HTTP 请求的消息头上加一个 User-Agent ( 用于跟踪 调试或者其他 ), 可以这样定义它 : useragent: name: User-Agent in: header required: true 然后像使用其他参数一样使用它 : 70

71 paths: /persons: - $ref: '#/parameters/useragent' 表单参数 有些 js-less-browser 的老浏览器不支持 POST JSON 数据, 比如在创建用户时, 只 能够以这样个格式请求 : POST /js-less-persons username=apihandyman&firstname=api&lastname=handyman 没有问题, 丝袜哥可以搞定 我们只需要把各个属性的 in 关键字定义 为 formdata, 然后设置 consumes 的媒体类型为 application/x-www-formurlencoded 即可 post: summary: Creates a person description: For JS-less partners consumes: - application/x-www-form-urlencoded # END #### produces: - text/html - name: username in: formdata # END #### required: true pattern: '[a-z0-9]{8,64}' 71

72 minlength: 8 maxlength: 64 - name: firstname in: formdata # END #### - name: lastname in: formdata - name: dateofbirth in: formdata # END #### format: date '204': description: Person succesfully created 文件参数 当我们要处理一个请求, 输入类型是文件时, 我们需要 : 使用 multipart/form-data 媒体类型 ; 设置参数的 in 关键字为 formdata; 设置参数的类型 (type) 为 file 比如 : 72

73 /images: - $ref: '#/parameters/useragent' post: summary: Uploads an image consumes: - multipart/form-data - name: image in: formdata type: file '200': description: Image's ID properties: imageid: 有时候我们想限定输入文件的类型 ( 后缀 ), 很不幸的是, 根据现在 V2.0 的规范暂时还做不到 The spec doesn t allow specifying a content type for specific form data parameters. It s a limitation of the spec. Ron Ratovsky comment in Swagger UI 609 issue 参数的媒体类型 一个 API 可以消费各种不同的媒体类型, 比如说最常见的是 application/json 类型的数据, 当然这不是 API 唯一支持的类型 我们可以在文档的根节点或者一个操作的根节点下添加关键字 consumes, 来定义这个操作能够消费的媒体类型 比如我们的 API 全部都接受 JSON 和 YAML 的数据, 那我们可以在文档的根节点下添加 : consumes: - application/json - application/x-yaml 73

74 如果某个操作 ( 比如上传图片的操作 ) 很特殊, 它可以通过自己添加 consumes 来覆盖全局设置 : /images: - $ref: '#/parameters/useragent' post: summary: Uploads an image consumes: - multipart/form-data # END #### - name: image in: formdata type: file '200': description: Image's ID properties: imageid: 5.2 高级响应消息定义 不带消息体的响应消息 不带消息体的响应很常见, 比如 HTTP 204 状态响应本身就表示服务器返回不带任何消息内容的成功消息 要定义一个不带消息体的响应很简单, 我们只需要写响应状态和描述就行了 : 74

75 post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body required: true description: The person to create. $ref: '#/definitions/person' '204': description: Person succesfully created. # END #### 响应消息中的必带参数和可选参数 与请求消息中类似, 我们使用 required 参数来表示, 比如请求一个用户信息时, 服务器必须返回 username, 可以这样写 : 75

76 Person: required: - username # END #### properties: firstname: lastname: username: pattern: '[a-z0-9]{8,64}' minlength: 8 maxlength: 64 dateofbirth: format: date lasttimeonline: format: date-time readonly: true 响应消息头 API 的返回结果不仅仅体现下 HTTP 状态和响应消息体, 还可以在响应消息头上做文章 比如我们可以限定一个 API 的使用次数和使用时间段, 在响应消息头中, 增加一个属性 X-Rate-Limit-Remaining 来表示 API 可调用的剩余次数, 增加另一个属性 X-Rate-Limit-Reset 来表示 API 的有效截止时间 76

77 post: summary: Creates a person description: Adds a new person to the persons list. - name: person in: body required: true description: The person to create. $ref: '#/definitions/person' '204': description: Person succesfully created. headers: X-Rate-Limit-Remaining: type: integer X-Rate-Limit-Reset: format: date-time # END #### 美中不足的是, 对于这种响应消息头的修改, 目前 2.0 规范暂时还不支持 一次定 义 处处使用 默认响应消息 我们在定义响应消息时, 通常会列举不同的 HTTP 状态结果 如果有些状态不在我们 API 文档的定义范围 ( 比如服务器需要返回 993 的状态 ), 该怎么处理呢? 这时需要通过关键字 default 来定义一个默认响应消息, 用于各种定义之外的状态响应, 比如 : 77

78 delete: summary: Deletes a person description: Delete a single person identified via its use rname '204': description: Person successfully deleted. headers: X-Rate-Limit-Remaining: type: integer X-Rate-Limit-Reset: format: date-time '404': $ref: '#/responses/persondoesnotexistresponse' '500': $ref: '#/responses/standard500errorresponse' default: $ref: '#/responses/totallyunexpectedresponse' # END #### 目前这个配置也不支持 一次定义, 处处使用 响应消息的媒体类型 与请求消息一样, 我们也可以定义响应消息所支持的媒体类型, 不同的是我们要用到关键字 produces ( 与请求消息中的 consumes 相对, 由此可见,API 文档描述的主体是服务提供者 ) 比如, 我们可以在文档的根路径下全局设置 : produces: - application/json - application/x-yaml 78

79 也可以在某个操作的根路径下覆盖设置 : /images/{imageid}: - $ref: '#/parameters/useragent' get: summary: Gets an image - name: imageid in: path required: true produces: - image/png - image/gif - image/jpeg - application/json - application/x-yaml # END #### '200': description: The image headers: X-Rate-Limit-Remaining: type: integer X-Rate-Limit-Reset: format: date-time '404': description: Image do not exists headers: X-Rate-Limit-Remaining: type: integer X-Rate-Limit-Reset: format: date-time '500': 79

80 $ref: '#/responses/standard500errorresponse' default: $ref: '#/responses/totallyunexpectedresponse' 5.3 定义某个参数只存在于响应消息中 如前章节 中已经提到的, 定义一个对象, 其中某个属性我们只希望在响应消息中携带, 而不希望在请求消息中携带, 应该用 readonly 关键字来表示 考虑到内容的完整性, 这里再介绍一下 比如 Person 对象中的 lasttimeonline 这个属性, 注册用户时我们不需要填写, 但是在获取用户信息时, 需要提供给服务消费者 : Person: required: - username properties: firstname: lastname: username: pattern: '[a-z0-9]{8,64}' minlength: 8 maxlength: 64 dateofbirth: format: date lasttimeonline: format: date-time readonly: true # END #### 80

81 第 6 章不要让 API 裸奔 这一章主要介绍 API 文档中如何描述安全相关的内容 6.1 定义安全 安全相关内容的定义一般放在 API 文档根目录下的 securitydefinition 中, 它包括一组具体的命名安全项, 每一个命名安全定义可能包括下面三种安全类型之一 :basic,apikey,oauth 基础鉴权 (Basic Authentication) 要定义一个基础 (basic) 鉴权, 我们只需要将 type 设置为 basic 即可 : securitydefinitions: UserSecurity: type: basic AdminSecurity: type: basic MediaSecurity: type: basic 这个例子中, 我们定义了三种安全说明 (UserSecurity,AdminSecurity, MediaSecurity), 都属于基础鉴权 API 秘钥鉴权 (API Key) 要定义一个 API 秘钥鉴权, 我们需要 : 设置 type 为 apikey 通过关键字 in 指示 api 秘钥所在位置 通常 api 秘钥会放在消息头 请求参数或者消息体中给安全项命个名字 81

82 securitydefinitions: UserSecurity: type: apikey in: header name: SIMPLE-API-KEY AdminSecurity: type: apikey in: header name: ADMIN-API-KEY MediaSecurity: type: apikey in: query name: MEDIA-API-KEY 在这个例子中, 我们定义了三个 apikey 类型的安全项 : UserSecurity 定义了一个名为 SIMPLE-API-KEY 的参数在消息头 (header) AdminSecurity 定义了一个名为 ADMIN-API-KEY 的参数在消息头 (header) MediaSecurity 定义了一个名为 MEDIA-API-KEY 的参数在请求参数中 Oauth2 鉴权 流程 (Flow) 和 URL 当我们定义个 Oauth2 类型的安全项上, 我们通常会定义 Oauth2 的流程 (flow) 和并根据选定的流程配置相应的鉴权地址 (authorizationurl) 和 / 或令牌地址 (tokenurl) 流程 所需要的 URL implicit authorizationurl( 鉴权地址 ) password tokenurl( 令牌地址 ) application accesscode tokenurl authorizationurl and tokenurl 比如 : 82

83 securitydefinitions: OauthSecurity: type: oauth2 flow: accesscode authorizationurl: ' tokenurl: ' 在这个例子中, 我们定义了一个 Oauth2 的安全项, 配置的流程是 accesscode 方 式, 同时配置了鉴权地址和令牌地址 作用范围 (scope) 我们借助关键字 scopes 并通过哈希键值对来还可以配置 Oauth2 安全项的作用范 围 (scope), 键值对的键表示作用范围名称 ; 值是它的相关描述, 比如 : securitydefinitions: OauthSecurity: type: oauth2 flow: accesscode authorizationurl: ' tokenurl: ' scopes: admin: Admin scope user: User scope media: Media scope 在这个例子中, 我们给 OauthSecurity 安全项添加了三个作用范围 (admin,user,media) 6.2 使用安全定义 现在我们已经在 securitydefinition 中定义好了安全项, 现在我们可以将将它们应用 到文档中了 使用的时候, 我们通过 security 关键字, 把安全项添加进去 基础鉴权 API 级别 83

84 securitydefinitions: UserSecurity: type: basic AdminSecurity: type: basic MediaSecurity: type: basic security: - UserSecurity: [] # END #### paths: /persons: 在这个例子中, 我们在 API 文档的根路径下直接使用了安全项 UserSecurity, 它的 作用范围是整个 API 文档 操作级别 比如我们在添加或者修改用户信息时, 需要进行管理员鉴权, 可以在 POST /persons 操作中增加安全项 : post: summary: Creates a person description: Adds a new person to the persons list. security: - AdminSecurity: [] # END #### 而在上传图片时, 需要进行媒体操作鉴权, 可以在 POST /images 操作中增加安全 项 : 84

85 /images: - $ref: '#/parameters/useragent' post: summary: Uploads an image security: - MediaSecurity: [] # END #### API 秘钥鉴权 使用方式和基础鉴权一样, 可以在 API 级别和操作级别使用 : securitydefinitions: UserSecurity: type: apikey in: header name: SIMPLE-API-KEY AdminSecurity: type: apikey in: header name: ADMIN-API-KEY MediaSecurity: type: apikey in: query name: media-api-key security: - UserSecurity: [] # END #### paths: /persons: 85

86 post: summary: Creates a person description: Adds a new person to the persons list. security: - AdminSecurity: [] Oauth2 鉴权 Oauth2 鉴权的使用和上面的两种鉴权方式基本相同, 不同之处在于我们可以指定它的哪一个作用范围 (scope) 比如 API 级别的鉴权 : securitydefinitions: OauthSecurity: type: oauth2 flow: accesscode authorizationurl: ' tokenurl: ' scopes: admin: Admin scope user: User scope media: Media scope security: - OauthSecurity: - user # END #### paths: /persons: 操作级别的鉴权 : 86

87 post: summary: Creates a person description: Adds a new person to the persons list. security: - OauthSecurity: - admin 在这个例子中, 作用范围 admin 将覆盖全局配置的作用范围 user 6.3 使用多种安全配置 OpenAPI 规范并没有限定我们只能使用一种安全项 下面的例子将展示如何使用多 种安全配置 安全定义 securitydefinitions: OauthSecurity: type: oauth2 flow: accesscode authorizationurl: ' tokenurl: ' scopes: admin: Admin scope user: User scope MediaSecurity: type: apikey in: query name: media-api-key LegacySecurity: type: basic 这个例子中, 我们定义了三种鉴权方式 全局安全配置 87

88 security: - OauthSecurity: - user - LegacySecurity: [] 这个配置的意思是用户可以通过两种方式中的任意一种来访问我们提供的 API 接 口 覆盖全局配置 post: summary: Creates a person description: Adds a new person to the persons list. security: - OauthSecurity: - admin - LegacySecurity: [] 在 POST /persons 操作中,OauthSecurity 的作用范围被覆写为 admin 此时用户 可以通过 admin 的 Oauth2 或者 legacysecurity 来鉴权使用这个操作 /images: - $ref: '#/parameters/useragent' post: summary: Uploads an image security: - MediaSecurity: [] 在 POST/images 操作中, 用 MediaSecurity 整体覆写了全局安全项, 用户只能通过 MediaSecurity 鉴权使用这个操作 第 7 章让文档的可读性更好 88

89 7.1 分类标签 (Tags) 通过关键字 tags 我们可以对文档中接口进行归类, tags 的本质是一个字符串 列表 tags 定义在文档的根路径下 单标签 比如说 GET /persons 属于用户 (Person) 这个分类的, 那么我们可以给它贴个标 签 : paths: /persons: - $ref: '#/parameters/useragent' get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. operationid: searchusers tags: - Persons # END #### 多标签 一个操作也可以同时贴几个标签, 比如 : 89

90 /js-less-consumer-persons: - $ref: '#/parameters/useragent' post: summary: Creates a person description: For JS-less partners operationid: createuserjs deprecated: true tags: - JSLess - Persons 贴上标签后, 在 Swagger Editor 和 Swagger UI 中能够自动归类, 我们可以按照标签 来筛选接口, 试试吧? 7.2 无处不在的描述文字 (Descriptions) description 这个属性几乎是无处不在, 为了提高文档的可读性, 我们应该在必 要的地方都加上描述文字 安全项的描述 90

91 securitydefinitions: OauthSecurity: description: New Oauth security system. Do not use MediaSecu rity or LegacySecurity. type: oauth2 flow: accesscode authorizationurl: ' tokenurl: ' scopes: admin: Admin scope user: User scope MediaSecurity: description: Specific media security for backward compatibil ity. Use OauthSecurity instead. type: apikey in: query name: media-api-key LegacySecurity: description: Legacy security system for backward compatibili ty. Use OauthSecurity instead. type: basic 模式 (Schema) 的描述 每一种模式 (Schema), 都会有一个标题 (title) 和一段描述, 比如 : definitions: Person: title: Human description: A person which can be the user itself or one of his friend 属性的描述 比如 : 91

92 properties: firstname: description: first name 参数的描述 paths: /persons: post: - name: person in: body required: true description: The person to create. $ref: '#/definitions/person' username: name: username in: path required: true description: The person's username pagesize: name: pagesize in: query description: Number of persons returned 操作的概述 (summary) 描述和操作 ID(operationId) 一个操作 (Operation) 通常都会包含概述和描述信息 而且我们还可以添加一个关键字 operationid, 这个关键字通常用来指示服务提供者对这个操作的处理函数的函数名 比如 : 92

93 paths: /persons: - $ref: '#/parameters/useragent' get: summary: Gets some persons description: Returns a list containing all persons. The li st supports paging. operationid: searchusers 响应消息的描述 paths: /persons: - $ref: '#/parameters/useragent' get: '200': description: A list of Person Standard500ErrorResponse: description: An unexpected error occured 响应消息头的描述 93

94 headers: X-Rate-Limit-Remaining: description: How many calls consumer can do type: integer X-Rate-Limit-Reset: description: When rate limit will be reset format: date-time 标签的描述 我们在 API 文档的根路径下添加了 tags 的定义, 对于其中的每一个标签, 我们都 可以添加描述信息 : tags: - name: Persons description: Everything you need to handle users and friends 7.3 在描述中使用 Markdown 语法 在绝大部分的 description 中, 我们可以使用 GFM(Github Flavored Markdown) 语法 多行描述 使用符号 然后在新行中打一个 tab( 注意 :YAML 的 tab 是两个空格 ), 就可以 编辑多行描述, 比如 : 94

95 '/persons/{username}/collecting-items': - $ref: '#/parameters/username' - $ref: '#/parameters/useragent' get: summary: Gets a person's collecting items list description: Returns a list containing all items this person is looki ng for. The list supports paging 简单使用 GFM 比如我们要强调, 可以这样写 : externaldocs: description: **Complete** documentation describing how to use this API url: 带信息组的描述 95

96 CollectingItem: discriminator: itemtype required: - itemtype properties: itemtype: description: An item can be of different type: type definition Vinyl #/definitions/vinyl VHS #/definitions/vhs AudioCassette #/definitions/audiocassette enum: - AudioCassette - Vinyl - VHS 带代码的描述 96

97 swagger: '2.0' info: version: title: Simple API description: A simple API to learn how to write OpenAPI Specification. This file uses almost every single aspect of the [Open API S pecification]( This API will use JSON. JSON looks like this: ```JSON { "key": "value", "anotherkey": "anothervalue" } 97

98 ### 7.4 示例数据 (Examples) 我们已经知道了用 Schema 来描述参数和属性, 有的时候, 用示例数据更有表现了 我们 可以使用关键字 `example` 来给原子属性或者对象添加示例数据 #### 原子属性的示例数据 ```YAML properties: firstname: description: first name example: John # END #### lasttimeonline: description: The last time this person was connected to the service as a format: date-time readonly: true example: T12:36:58.014Z # END #### 对象属性的示例数据 98

99 Persons: title: Humans description: A list of users or friends required: - items properties: items: description: Array containg the list type: array minitems: 10 maxitems: 100 uniqueitems: true items: $ref: '#/definitions/person' example: - firstname: Robert lastname": Doe username": robdo dateofbirth: lasttimeonline: T14:36:58.014Z - firstname: Jane lastname: Doe username: jdoe123 dateofbirth: lasttimeonline: T19:23:59.014Z # END #### 定义的示例数据 跟普通属性一样, 定义的对象也能添加示例数据 : 99

100 MultilingualErrorMessage: title: MultiLingualMultiDeviceErrorMessage description: An multilingual error message (hashmap) with a long and a short description additionalproperties: $ref: '#/definitions/errormessage' properties: defaultlanguage: $ref: '#/definitions/errormessage' example: defaultlanguage: longmessage: We're deeply sorry but an error occured shortmessage: Error fr: longmessage: Nous sommes dã solã mais une erreur est su rvenu shortmessage: Erreur # END #### 响应消息的示例数据 我们甚至可以添加响应消息级别的示例数据 : '/persons/{username}/collecting-items': get: '200': examples: application/json: { "totalitems": 10, "totalpage": 4, 100

101 "pagesize": 3, "currentpage": 2, "items": [ { "itemtype": "Vinyl", "maxprice": 20, "imageid": " eb-4bac-b32e-cd5b7196 de71", "albumname": "Captain Future Original Soundt rack", "artist": "Yuji Ohno" }, { "itemtype": "VHS", "maxprice": 10, "imageid": "b74469bc-e6a1-4a90-858a-88ef ", "movietitle": "Star Crash", "director": "Luigi Cozzi" }, { "itemtype": "AudioCassette", "maxprice": 10, "imageid": "b74469bc-e6a1-4a90-858a-88ef ", "albumname": "Star Wars", "artist": "John Williams" } ] } # END #### '404': $ref: '#/responses/persondoesnotexistresponse' '500': $ref: '#/responses/standard500errorresponse' default: $ref: '#/responses/totallyunexpectedresponse' 101

102 7.4.5 示例数据的优先级 如果我们在各个级别 ( 比如参数 对象 定义 响应消息 ) 都添加了示例数据 支 持 OpenAPI 规范的各解析工具都是以最高级别的定义为准 7.5 标记为弃用 我们可以通过关键字 deprecated 置为 true 来标记接口的弃用状态, 比如 : /js-less-consumer-persons: - $ref: '#/parameters/useragent' post: summary: Creates a person description: For JS-less partners operationid: createuserjs deprecated: true 7.6 链接到外部文档 一般来说, 项目中不光只有一篇 API 文档, 还应该有些描述 application key, 测试用例, 操作链以及其他内容的文档, 这些文档一般是单独成篇的 如果在描述某个接口时, 我们想链接这些文档, 可以通过关键字 externaldoc 来添加, 例如 : externaldocs: description: Complete documentation describing how to use this API url: 102

103 /images: - $ref: '#/parameters/useragent' post: summary: Uploads an image description: Upload an image, will return an image id. operationid: storeimage externaldocs: description: How to upload media url: 第 8 章分而治之 根据前面几张的知识, 我们已经可以轻松的构建一个复杂的 API 文档了 可是作为一个学过 Clean Code 的程序员, 我们并不希望所有的接口 定义都在一个大而全的上帝文件里 这一章我们一起来学习拆分文件 8.1 JSON 指针 我们在第 2 章已经知道了怎么定义一个可重用的对象, 已经如何使用定义, 重温一 下 : 103

104 /persons/{username}: get: summary: Gets a person description: Returns a single person for its username. - name: username in: path required: true description: The person's username 200: description: A Person $ref: "#/definitions/person" 404: description: The Person does not exists. definitions: Person: required: - username properties: firstname: lastname: username: Persons: type: array items: $ref: "#/definitions/person" 在使用的时候我们这样写 :$ref: "#/definitions/person", $ref 就是 JSON 指针 ( 参见定义 RFC6901) 例子中的这个指针指向当前文档根路径( # ) 下的 definitions 下的 Person JSON 指针不仅可以指向当前文件, 还可以指向其他文件 104

105 8.2 基础拆分 引用本地文件 还是上面这个例子, 我们在当前文档的同一目录下, 新建的一个文件叫 person.yaml, 然后把 Person 的定义拆出来, 放在其中 Person: required: - username properties: firstname: lastname: username: 在当前文档中把引用 Person 定义的地方修改为 : $ref: "person.yaml#/person" 编辑器报错 把上面的代码放到 Swagger Editor 中编辑, 编辑器预览中可能会报错 : 提示找不到 person.yaml 文件 这是因为我们没有指定正确的编辑器的指针解析基 础路径 ( Pointer Resolution Base Path ) 105

106 解决的办法是 : 进入编辑器的 Preferences -> Preferences 菜单, 修改 Pointer Resolution Base Path 为 : 考虑到缓存的原因, 如果错误依然存在, 请刷新浏览器 文件夹 如果引用子文件夹下的文件, 我们可以这样写 : $ref: "folder/person.yaml#/person" 如果引用上级文件夹下的文件, 我们可以这样写 : Persons: type: array items: $ref: "../folder/person.yaml#/person" 引用远程文件 如果我们想引用一个远程文件, 应该怎么做呢? 可以这样写 : $ref: 但是需要注意的是 : 服务器必须提供跨域 (CORS) 访问服务 如果要通过本地服务器上的 8080 端口引用文件, 我们可以这样写 : $ref: " 考虑两种比较特别的情况 : 远端文件引用 " 本地文件 " 106

107 比如说, 我们引用了 : $ref: " ons" 这个远端文件 但是 persons.yaml 又引用了与它在同一目录下的 person.yaml 文件, 这个时候语法分析器会在 localhost:8080 上面找 person.yaml 文件, 而不会查找我们本地的 person.yaml 远端文件引用 更 远端文件如果理解了 这个例子, 我们就知道不管怎么引用, 都是在相对于被引用的文件下来进行查找的 整理一个文件中的多个定义 比如我们在一个文件中, 需要把定义分成几类, 可以这样做 : SomeDefinitions: Person: required: - username properties: firstname: lastname: username: OtherDefinitions: Persons: type: array items: $ref: "#/SomeDefinitions/Person" 107

108 Person 归属于 SomeDefinitions 这一类, Persons 归属 于 OtherDefinitions 这一类 那么我们在引用这两个定义时, 分别应该这样书 写 : $ref: "definitions.yaml#/otherdefinitions/persons" $ref: "definitions.yaml#/somedefinitions/person" 有点像命名空间的概念 8.3 实战切分的思路 结构化切分思路 : 先把 API 文档的头部 info 切下来, 放在 info.yaml, 然后分别切分 paths.yaml, definitions.yaml, responses.yaml, parameters. yaml 等文件, 最后合并到 main.yaml ; 分层切分思路 : 分别按照功能和层次, 将文件切分为 base.yaml 或 common.yaml, 然后是各个模块的 xxx-paths.yaml, 然后是各个定义的 xxx-definitions.yaml 其他思路 需要注意的是, 不管怎么切分, 有一个原则必须谨记 : 切分出来的子文档, 必须遵循 OpenAPI 规范, 能够通过编辑器的校验, 不然切分得再漂亮也是徒劳 The END??? NO! 接下来, 就看你的了! 附录 108

109 Arnaud Lauret 大神为了简化 OpenAPI 规范的阅读, 维护了一个 openapispecification-visual-documentation 的项目, 通过动态导图的方式把规范完整呈 现, 懒人必备 点击此处查看 109