定义
OpenAPI 规范(OAS),是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好,那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。
如果您遵循 OpenAPI 规范来定义您的 API,那么您就可以用文档生成工具来展示您的 API,用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码,用自动测试工具进行测试等等。
开放API文档
一(或多)份用来定义或描述一个API的文档。
路径模板
路径模板指用大括号标记来标记一段URL作为可替换的路径参数。
媒体类型
以下是一些媒体类型定义的示例:
text/plain; charset=utf-8
application/json
application/vnd.github+json
application/vnd.github.v3+json
application/vnd.github.v3.raw+json
application/vnd.github.v3.text+json
application/vnd.github.v3.html+json
application/vnd.github.v3.full+json
application/vnd.github.v3.diff
application/vnd.github.v3.patch
HTTP状态码
语义化版本的
主版本号
、次版本号
部分(比如3.0
)应当被用来标记开放API规范的特性变动。通常 .修订号
版本被用来表示本文档文档的错误修正而不是特性变动。支持开放API规范3.0的工具应该兼容所有3.0.*的版本,工具不应当关注修订版本号,比如3.0.0
和3.0.1
对它来说应该没有任何区别。此后开放API规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此
3.1.0
版本的规范应当可以在面向3.0.0
版本规范开发的工具内使用。一份遵从开放API规范的文档是一个自包含的JSON对象,可以使用JSON或YAML格式编写。
比如一个字段有一组值,用JSON格式表示为:
{
"field": [ 1, 2, 3 ]
}
规范内的所有字段名都是小写。
字段分为两种:固定字段和模式字段。固定字段的字段名是确定的,模式字段的字段名需要符合一定的模式。
如果一个对象里有模式字段,那么在这个对象里的模式字段的名字不能有重复的。
注意: 虽然API文档是使用 YAML 或 JSON 格式书写的,但是API的请求体和响应体或者其他内容可以是任何格式。
推荐将根开放API文档命名为
openapi.json
或 openapi.yaml
。在 OAS 中的原始数据类型是基于 JSON Schema Specification Wright Draft 00 所支持的类型。注意
integer
也作为一个被支持的类型并被定义为不包含小数或指数部分的 JSON 数字。 null
不是一个被支持的类型 (查看 nullable
来获得替代解决方案)。 Models 使用 Schema Object 定义,这是一个 JSON Schema Specification Wright Draft 00 的扩展。原始类型可以有一个可选的修饰属性:
format
。 OAS 使用多个已知的格式来丰富类型定义。尽管如此,为了文档的需要,format
属性被设计为一个 string
类型的开放属性值,可以包含任意值。比如 "email"
, "uuid"
等未被此规范定义的格式也可以被使用。没有被定义的 format
属性类型遵从 JSON Schema 中的类型定义。无法识别某个 format
值 的工具应该回退到 type
值,就像 format
未被指定一样。被 OAS 定义的格式:
通用名 | 备注 | ||
integer | integer | int32 | 32 位有符号 |
long | integer | int64 | 64 位有符号 |
float | number | float | |
double | number | double | |
string | string | | |
byte | string | byte | base64 编码的支付 |
binary | string | binary | 任意 8进制序列 |
boolean | boolean | | |
date | string | date | |
dateTime | string | date-time | |
password | string | password | 告知输入界面不应该明文显示输入信息。 |
整个规范中的
description
字段被标记为支持 CommonMark markdown 格式。 OpenAPI 相关的工具在支持 CommonMark 0.27 中描述的富文本格式方面至少需要支持渲染 markerdown。相关工具为了安全考虑可以选择忽略某些 CommonMark 特性。在接下来的叙述中,如果一个字段没有被明确的标记为 必选 或者被描述为 必须 或 应当,那么可以认为它是一个 可选 字段
固定字段
字段名 | 类型 | 描述 |
openapi | string | |
info | 必选。此字段提供API相关的元数据。相关工具可能需要这个字段。 | |
servers | ||
paths | 必选。对所提供的API有效的路径和操作。 | |
components | 一个包含多种结构的元素。 | |
security | 声明API使用的安全机制。The list of values includes alternative security requirement objects that can be used. 认证一个请求时仅允许使用一种安全机制。单独的操作可以覆盖这里的定义。 | |
tags | 提供更多元数据的一系列标签,标签的顺序可以被转换工具用来决定API的顺序。不是所有被Operation 对象用到的标签都必须被声明。没有被声明的标签可能被工具按自己的逻辑任意整理,每个标签名都应该是唯一的。 | |
externalDocs |
这个对象提供API的元数据。如果客户端需要时可能会用到这些元数据,而且可能会被呈现在编辑工具或者文档生成工具中。
固定字段
字段名 | 类型 | 描述 |
title | string | 必选. 应用的名称。 |
description | string | |
termsOfService | string | 指向服务条款的URL地址,必须是URL地址格式。 |
contact | 所开放的API的联系人信息。 | |
license | 所开放的API的证书信息。 | |
version | string |
Info 对象示例
{
"title": "Sample Pet Store App",
"description": "This is a sample server for a pet store.",
"termsOfService": "http://example.com/terms/",
"contact": {
"name": "API Support",
"url": "http://www.example.com/support",
"email": "[email protected]"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "1.0.1"
}
title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://www.example.com/support
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
所公开的API的联系人信息
固定字段
字段名 | 类型 | 描述 |
name | string | 人或组织的名称。 |
url | string | 指向联系人信息的URL地址,必须是URL地址格式。 |
email | string | 人或组织的email地址,必须是email地址格式。 |
Contact 对象示例
公开API的证书信息。
固定字段
字段名 | 类型 | 描述 |
name | string | 必选. API的证书名。 |
url | string | 指向API所使用的证书的URL地址,必须是URL地址格式。 |
License 对象示例
{
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
表示一个服务器的对象。
固定字段
字段名 | 类型 | 描述 |
url | string | 必选. 指向目标主机的URL地址。这个URL地址支持服务器变量而且可能是相对路径,表示主机路径是相对于本文档所在的路径。当一个变量被命名为类似 { brackets} 时需要替换此变量。 |
description | string | |
variables | 一组变量和值的映射,这些值被用来替换服务器URL地址内的模板参数。 |
Server 对象示例
单个服务器可以这样描述:
{
"url": "https://development.gigantic-server.com/v1",
"description": "Development server"
}
url: https://development.gigantic-server.com/v1
description: Development server
{
"servers": [
{
"url": "https://development.gigantic-server.com/v1",
"description": "Development server"
},
{
"url": "https://staging.gigantic-server.com/v1",
"description": "Staging server"
},
{
"url": "https://api.gigantic-server.com/v1",
"description": "Production server"
}
]
}
servers:
- url: https://development.gigantic-server.com/v1
description: Development server
- url: https://staging.gigantic-server.com/v1
description: Staging server
- url: https://api.gigantic-server.com/v1
description: Production server
以下内容展示了如何使用变量来配置服务器:
{
"servers": [
{
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]
}
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
description: The production API server
variables:
username:
# note! no enum here means it is an open value
default: demo
description: this value is assigned by the service provider, in this example `gigantic-server.com`
port:
enum:
- '8443'
- '443'
default: '8443'
basePath:
# open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
default: v2
表示可用于服务器URL地址模板变量替换的对象。
固定字段
字段名 | 类型 | 描述 |
enum | [ string ] | 一组可枚举字符串值,当可替换选项只能设置为固定的某些值时使用。 |
default | string | |
description | string |