OpenAPI 规范摘要

介绍

OpenAPI 规范（OAS）定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查（既方便人类学习和阅读，也方便机器阅读）。正确定义 OAS 后，开发者可以使用最少的实现逻辑来理解远程服务并与之交互。

此外，文档生成工具可以使用 OpenAPI 规范来生成 API 文档，代码生成工具可以生成各种编程语言下的服务端和客户端代码，测试代码和其他用例。

数据类型

OAS 使用几种已知的 format 格式来详细定义所使用的 type 数据类型。
format属性是开放的字符串值，可以是自定义的任意类型值，比如：email、uuid。
OAS 定义的 formats 类型如下：

-通用名称-	数据类型	数据格式	描述
integer	integer	int32	signed 32 bits，32位有符号数
long	integer	int64	signed 64 bits，64位有符号数
float	number	float
double	number	double
string	string
byte	string	byte	base64 encoded characters，base64 编码字符
binary	string	binary	any sequence of octets
boolean	boolean
date	string	date	参考 RFC3339 - full-date
dateTime	string	date-time	参考 RFC3339 - date-time
password	string	password	UI 提示隐藏输入

OpenAPI 根对象

这是 OpenAPI 的根文档对象。

# OpenAPI 规范版本号
openapi: 3.0.0# API 元数据信息
info:# 服务器连接信息
servers:# API 的分组标签
tags: # 对所提供的 API 有效的路径和操作
paths:# 一个包含多种纲要的元素，可重复使用组件
components:# 声明 API 使用的安全机制
security:# 附加文档
externalDocs:

Info 对象

Info 对象描述 API 的元数据信息。

# API 元数据信息
info:title:  xx开放平台接口文档                    # 应用的名称description: |                          简短的描述信息，支持 markdown 语法。 | 表示换行，< 表示忽略换行。version: "1.0.0"                            # API 文档的版本信息termsOfService: 'http://swagger.io/terms/'  # 指向服务条款的 URL 地址contact:                                    # 所开放的 API 的联系人信息name: API Support                           # 人或组织的名称url: http://www.example.com/support         # 指向联系人信息的 URL 地址email: apiteam@swagger.io                   # 人或组织的 email 地址license:                                    # 所开放的 API 的证书信息。name: Apache 2.0url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

Server 对象

所有的 API 端点都是相对于基本 URL 的。例如，假设 https://api.example.com/v1 的基本 URL 中，/users 端点指的是 https://api.example.com/v1/users。

https://api.example.com/v1/users?role=admin&status=active
\ __________________ / \__/ \ ______________________ /服务器URL      端点路径        查询参数

Server 表示一个服务器的对象。这里通常填写测试服务器或者生产服务器的 IP 地址、端口版本号等信息（指定基本 URL）。

# 服务器连接信息
servers:- url: https://development.gigantic-server.com/v1description: 开发服务器- url: https://staging.gigantic-server.com/v1description: 测试服务器- url: https://api.gigantic-server.com/v1description: 生产服务器

Tag 对象

Tag 对象用于对 path 对象中的 API 进行分组，可以更美观的生成文档。

# API 的分组标签
tags: - name: petdescription: 与宠物相关的接口externalDocs:description: 外部文档url: 'http://swagger.io'- name: storedescription: 宠物商店- name: userdescription: 用户操作相关externalDocs:description: 外部文档url: 'http://swagger.io'

External Documentation 对象

允许引用外部资源来扩展文档。

# 附加文档
externalDocs:description: Find out more about Swaggerurl: 'http://swagger.io'

Components 对象

components 对象包含开放 API 规范规定的各种可重用组件。当没有被其他对象引用时，在这里定义的组件不会产生任何效果。

# 一个包含多种纲要的元素，可重复使用组件
components:schemas:responses:parameters:examples:requestBodies:headers:securitySchemes:links:callbacks:

Path 对象

定义各个端点和操作的相对路径。

# 对所提供的 API 有效的路径和操作
paths:/pet/{petId}:get:tags:- petsummary: 简要总结，描述此路径内包含的所有操作。description: 详细说明，用于描述此路径包含的所有操作。operationId: getPetById      # 此操作的唯一标识符parameters:                 # 参数列表- name: petIdin: pathdescription: 路径参数，宠物 ID。required: trueschema:type: integerformat: int64responses:                  # 接口响应内容'200':description: 操作成功content:application/json:schema:type: objectproperties:id:type: integerformat: int64category:type: objectproperties:id:type: integerformat: int64name:type: stringname:type: stringexample: doggiephotoUrls:type: arrayitems:type: stringtags:type: arrayitems:type: objectproperties:id:type: integerformat: int64name:type: stringstatus:type: stringdescription: 宠物在商店的状态enum:- available- pending- sold'400':description: 无效的 id'404':description: 找不到指定的资源security:             # 作用于此操作的安全机制- api_key: []         # 可以声明一个空数组来变相的移除顶层的安全声明

返回的 Pet 对象详解：

使用 components 对象进行优化：

# 对所提供的 API 有效的路径和操作
paths:'/pet/{petId}':get:tags:- petsummary: 简要总结，描述此路径内包含的所有操作description: 详细说明，用于描述此路径包含的所有操作operationId: getPetById      # 此操作的唯一标识符parameters:                  # 参数列表- name: petIdin: pathdescription: pet IDrequired: trueschema:type: integerformat: int64responses:                  # 响应列表'200':description: 操作成功content:application/json:schema:$ref: '#/components/schemas/Pet''400':description: 无效的 id'404':description: 找不到指定的资源security:             # 作用于此操作的安全机制- api_key: []         # 可以声明一个空数组来变相的移除顶层的安全声明components:schemas:Category:type: objectproperties:id:type: integerformat: int64name:type: stringTag:type: objectproperties:id:type: integerformat: int64name:type: stringPet:type: objectproperties:id:type: integerformat: int64category:$ref: '#/components/schemas/Category'name:type: stringexample: doggiephotoUrls:type: arrayitems:type: stringtags:type: arrayitems:$ref: '#/components/schemas/Tag'status:type: stringdescription: 宠物在商店的状态enum:- available- pending- sold

通过 components 对象封装可重用对象，然后通过 $ref标签进行引用：

Parameter 参数对象

描述一个操作参数。
参数位置（in）的值：

参数位置	描述	示例
path	参数的值是 URL 操作路径的一部分	/ `items/{itemId}`，路径参数是`{itemId}`
query	追加在 URL 地址之后的参数	`/items?id=###`，查询参数是`id`
header	请求中使用的自定义请求头
cookie	用于传递特定的 cookie 值

一个值数组，数组元素为 64 位整数值的请求头参数：

name: token
in: header
description: 需要作为 HTTP header 请求头传递的 token 参数
required: true
schema:type: arrayitems:type: integerformat: int64
style: simple

路径 /pet/{petId}下的 petId 路径参数：

parameters:               # 参数列表（以“数组”格式描述参数）- name: petId             # 参数名称in: path                # 参数的位置 path/query/header/cookiedescription: URL 路径参数，宠物 ID。required: true          # 是否是必选参数，path 路径下的参数必须为 true。deprecated: false       # 参数是否被弃用allowEmptyValue: false  # 是否允许传递空参数，仅在路径为 query 下有效。schema:                 # 描述参数的结构type: integerformat: int64example: 123456

一个值类型为字符串的路径参数：

parameters:               # 参数列表（以“数组”格式描述参数）- name: username       # 一个值类型为字符串的路径参数in: pathdescription: URL 路径参数，用户名。required: trueschema:type: stringpattern: "[a-z0-9]{8,64}" # 正则表达式minLength: 8              # 字符串的最小长度maxLength: 64             # 字符串的最大长度

一个值类型为字符串的可选查询参数，允许通过通过重复参数来传递多个值：

parameters: # 参数列表- name: idin: querydescription: 通过 id 查询对象。required: false   # 可选的查询参数schema:           # schema - 参数的结构type: arrayitems:            # 只有 array 类型 才有 items 项，描述数组项的数据类型type: stringstyle: form       # style - 描述如何序列化参数？explode: true     # 生成带分隔符的参数值

通过状态值（数组类型）查询，可以传入多个值：
/？status="["available","pending"]"

parameters:- name: statusin: querydescription: Status values that need to be considered for filterrequired: trueexplode: trueschema:type: arrayitems:type: stringenum: # 该参数是一个枚举类型- available- pending- solddefault: available  # 默认枚举类型

URL 请求路径中添加查询参数，实现分页输出：
GET https://example.com/v1/resources?pageSize=10&pageNumber=1

parameters:- name: pageSizein: querydescription: 每页返回的数量type: integerformat: int32minimum: 0             # 最小值exclusiveMinimum: true  # 数值必须 > 最小值maximum: 100           # 最大值exclusiveMaximum: false # 数值必须 < 最大值multipleOf: 10         # 数值必须是 multipleOf 的整数倍- name: pageNumberin: querydescription: 当前页码type: integer

Request Body 请求体对象

定义请求体。

paths:/pet:post:tags:- petsummary: 向商店中添加新的宠物operationId: addPetresponses:'405':description: 非法的操作requestBody:    # 请求体description: 需要被添加进商店的 Pet 对象required: true # 请求体是否被包含在请求中，默认值 falsecontent:      # 请求体的内容application/json:schema:$ref: '#/components/schemas/Pet'

为了方便重用，requestBody 的内容也可以放到 components 对象的 requestBodies 中：

# 对所提供的 API 有效的路径和操作
paths:/pet:post:tags:- petsummary: 向商店中添加新的宠物operationId: addPetresponses:'405':description: 非法的操作requestBody:    # 请求体$ref: '#/components/requestBodies/Pet'components:schemas:Category:type: objectproperties:id:type: integerformat: int64name:type: stringTag:type: objectproperties:id:type: integerformat: int64name:type: stringPet:type: objectrequired:       # 必填字段- name- photoUrlsproperties:id:type: integerformat: int64category:$ref: '#/components/schemas/Category'name:type: stringexample: doggiephotoUrls:type: arrayitems:type: stringtags:type: arrayitems:$ref: '#/components/schemas/Tag'status:type: stringdescription: 宠物在商店的状态enum:- available- pending- soldrequestBodies:Pet:description: 需要被添加进商店的 Pet 对象required: true          # 请求体是否被包含在请求中，默认值 falsecontent:                # 请求体的内容application/json:schema:$ref: '#/components/schemas/Pet'

Media Type 类型

文件上传和下载

# 使用 base64 编码传输的内容
schema:type: stringformat: base64# 以二进制（octet-stream，八位字节流）传输的内容
schema:type: stringformat: binary

一个使用 POST 操作提交文件的 requestBody看起来像下面这样:

requestBody:content:application/octet-stream:# any media type is accepted, functionally equivalent to `*/*`# 任何媒体类型都被接受，功能上等同于 `* / *`schema:# a binary file of any type# 任何类型的二进制文件type: stringformat: binary

此外，可以指定明确的媒体类型：

# 可以指定多个特定媒体类型
requestBody:content:# png 或 jpeg 类型的二进制文件'image/jpeg':schema:type: stringformat: binary'image/png':schema:type: stringformat: binary

为了同时上传多个文件，必须指定 multipart 媒体类型。

requestBody:content:multipart/form-data:schema:properties:# 属性名称 'file' 将用于所有文件file:type: arrayitems:type: stringformat: binary

使用 multipart/form-data 作为 Content-Type 来传送请求体是很常见的做法。

当定义 multipart 内容的输入参数时必须指定 schema 属性。这不但支持复杂的结构而且支持多文件上传机制。

requestBody:content:multipart/form-data:schema:type: objectproperties:id:type: stringformat: uuidaddress:# default Content-Type for objects is `application/json`# 如果属性是复杂对象或者复杂对象的数组，那么默认的 Content-Type 是 application/jsontype: objectproperties: {}profileImage:# default Content-Type for string/binary is `application/octet-stream`# 如果属性是 type: string 与 format: binary 或 format: base64(也就是文件对象) 的组合，那么默认的 Content-Type 是 application/octet-streamtype: stringformat: binarychildren:# default Content-Type for arrays is based on the `inner` type (text/plain here)# 如果属性是一个原始值或者是一个原始值的数组，那么默认的 Content-Type 是 text/plaintype: arrayitems:type: stringaddresses:# default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)type: arrayitems:type: '#/components/schemas/Address'

Encoding 对象

对具体属性的 Content-Type 的编码。默认值取决于属性的类型：

application/octet-stream 编码适用于 binary 格式的 string；
text/plain 适用于其他原始值；
application/json 适用于 object；
对于 array 值类型的默认值取决于数组内元素的类型，默认值可以是明确的媒体类型 (比如 application/json), 或者通配符类型的媒体类型 (比如 image/*), 又或者是用分号分隔的两种媒体类型。

Encoding 对象示例：

requestBody:content:multipart/mixed:schema:type: objectproperties:id:# default is text/plaintype: stringformat: uuidaddress:# default is application/jsontype: objectproperties: {}historyMetadata:# need to declare XML format!description: metadata in XML formattype: objectproperties: {}profileImage:# default is application/octet-stream, need to declare an image type only!type: stringformat: binaryencoding:historyMetadata:# require XML Content-Type in utf-8 encodingcontentType: application/xml; charset=utf-8profileImage:# only accept png/jpegcontentType: image/png, image/jpegheaders:X-Rate-Limit-Limit:description: The number of allowed requests in the current periodschema:type: integer

Responses 对象

描述一个操作可能发生响应的响应码与响应包含的响应体的对象。
一份 API 文档不必包含所有可能响应码，因为有些状态码无法提前预知。尽管如此，一份文档还是应当包含所有成功的响应和任何已知的错误响应。
default 字段可以用来标记一个响应适用于其他未被规范明确定义的 HTTP 响应码的默认响应。
一个 Responses 对象必须至少包含一个响应码，而且是成功的响应。
一个代表成功操作的 200 响应和一个代表其他操作状态的默认响应（暗示是一个错误）：

'200':description: 操作成功返回的对象content:application/json:schema:$ref: '#/components/schemas/Pet'
default:description: Unexpected error，未知的错误content:application/json:schema:$ref: '#/components/schemas/ErrorModel'

带 HTTP 头的普通文本类型的响应：

description: 响应简单的字符串
content:text/plain:schema:type: stringexample: 'whoa!'
headers:X-Rate-Limit-Limit:description: 当前期间允许的请求数目schema:type: integerX-Rate-Limit-Remaining:description: 当前期间的剩余请求数schema:type: integerX-Rate-Limit-Reset:description: 当前期间剩余的秒数schema:type: integer

Response 对象

单个 API 操作的响应对象。
一个包含复杂类型的数组格式的响应：

responses:'200':description: successful operationcontent:application/json:schema:type: array  # 返回一个数组，数组中每个值都是 Pet 对象。items:$ref: '#/components/schemas/Pet'

字符串响应：

description: 响应一个字符串
content:text/plain:schema:type: string

带 HTTP 头的普通文本类型的响应：

description: 响应一个字符串
content:text/plain:schema:type: stringexample: 'whoa!'
headers:X-Rate-Limit-Limit:description: 当前期间允许的请求数schema:type: integerX-Rate-Limit-Remaining:description: 当前期间剩余请求数schema:type: integerX-Rate-Limit-Reset:description: 当前时段剩余的秒数schema:type: integer

没有返回值的响应：

responses:'400':description: Invalid ID supplied'404':description: Pet not found'405':description: Validation exception

Header 对象

Header 对象的结构与 Parameter 对象的结构相似，并添加以下规则：

name 属性不必指定！
in 属性不必指定！
受 loaction影响的所有特征必须适用于 header 位置，例如 style 属性。

数据类型为 integer 的 header 对象示例：

headers:X-Rate-Limit-Limit:description: 当前期间允许的请求数schema:type: integerX-Rate-Limit-Remaining:description: 当前期间剩余请求数schema:type: integerX-Rate-Limit-Reset:description: 当前时段剩余的秒数schema:type: integer

Reference 对象

一个允许引用规范内部的其他部分或外部规范的对象。
示例：

$ref: '#/components/schemas/Pet'

Schema 对象

Schema 对象用于定义输入和输出的数据类型。这些类型可以是对象，也可以是原始值和数组。
字符串示例：

type: string
format: email

模型示例：

type: object
required:
- name
properties:name:type: stringaddress:$ref: '#/components/schemas/Address'age:type: integerformat: int32minimum: 0

Security Schema 对象

securitySchemes 和 security 关键字用于描述 API 中使用的身份验证方法。
components 对象下的 securitySchemas 对象示例：

# 一个包含多种纲要的元素，可重复使用组件
components:securitySchemes:petstore_auth:type: oauth2flows:implicit:authorizationUrl: 'http://petstore.swagger.io/oauth/dialog'scopes:'write:pets': modify pets in your account'read:pets': read your petsapi_key:type: apiKeyname: api_keyin: header

Basic Authentication Sample

基础（basic）鉴权。

components:securitySchemes:BasicAuth:type: httpscheme: basic

type 字段用于描述 security scheme 的类型。有效值包括 apiKey、http、oauth2、openIdConnect。

API Key Sample

API 秘钥鉴权。

securitySchemes:api_key:type: apiKeyname: api_key  # name 用于 header、 query 或 cookie 的参数名字in: header     # 指定 API 密钥的位置。有效值包括：query、header、cookie

通过关键字 in 指示 API 秘钥所在位置。通常 API 秘钥会放在消息头、请求参数或者消息体中。

JWT Bearer Sample

type: http
scheme: bearer
bearerFormat: JWT

bearerFormat 用于提示客户端所使用的 bearer token 的格式。Bearer token 通常通过授权服务器生成，所以这个字段最主要的目的是用来记录这个信息。

隐含的 OAuth2 示例

OAuth2 鉴权。
当我们定义 OAuth2 类型的安全项时，我们通常会定义 OAuth2 的流程（flow）和并根据选定的流程配置相应的鉴权地址（authorizationUrl）和/或令牌地址（tokenUrl）。
OAuth2 的流程（Flow）有如下四个：

流程	所需要的 URL
implicit	authorizationUrl（鉴权地址）
password	tokenUrl（令牌地址）
application	tokenUrl
accessCode	authorizationUrl and tokenUrl

示例：

securitySchemes:petstore_auth:type: oauth2description: 对 security scheme 的简短描述。flows: # 一个包含所支持的 flow types 的配置信息的对象。implicit: # OAuth 隐式流的配置authorizationUrl: 'http://petstore.swagger.io/oauth/dialog' # 此流程所需的鉴权地址scopes: # 此 OAuth2 安全方案的作用范围'write:pets': modify pets in your account'read:pets': read your pets

OAuth Flow 对象示例：

type: oauth2
flows: # 一个包含所支持的 flow types 的配置信息的对象。implicit: # OAuth 隐式流的配置authorizationUrl: https://example.com/api/oauth/dialog # 此流程所需的鉴权地址scopes: # 此 OAuth2 安全方案的作用范围write:pets: modify pets in your accountread:pets: read your petsauthorizationCode: # OAuth 授权码流程的配置authorizationUrl: https://example.com/api/oauth/dialogtokenUrl: https://example.com/api/oauth/token # 此流程所需的令牌地址。scopes:write:pets: modify pets in your accountread:pets: read your pets

原文地址：

作者：独木舟的木
链接：https://www.jianshu.com/p/5365ef83252a
来源：简书