OpenApi 规范(OpenApi Spec)
fka Swagger RESTful API 文档规范
版本2.0(Version 2.0)
文中所使用到的”MUST”,”MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”和”OPTIONAL”均遵循RFC 2119定义。
Swagger™ 是一个用于描述文档的RESTful API项目。
Swagger 规范定义了描述这种API所需的一组文件。这些文件可以 Swagger-UI 项目用来显示API和Swagger的代码生成生成各种语言的客户。额外的实用程序也可以利用生成的文件,例如测试工具。
版本(Version) | 日期(Date) | 说明(Notes) |
2.0 | 2014-09-08 | 发布 Swagger 2.0 |
1.2 | 2014-03-14 | 正式文件的初步发布。 |
1.1 | 2012-08-22 | 发布 Swagger 1.1 |
1.0 | 2011-08-10 | 首次发布 Swagger 规格 |
路径模板(Path Templating)
路径模板是指使用大括号
({})
来标记URL路径的一部分,使用路径参数作为可替换的参数。MIME类型(Mime Types)
可能MIME类型定义的一些示例:
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状态码(HTTP Status Codes)
根据Swagger的规范描述RESTful API的文件被表示为JSON对象,并符合JSON标准。YAML作为JSON的超集,也可以用来表示一个Swagger的规范文件。
例如,如果字段被认为具有数组值,那么将使用JSON数组表示:
{
"field" : [...]
}
当使用JSON描述API时,它不会将JSON输入/输出强加给API本身。
规范中的所有字段名称都是大小写敏感的。
该模式公开了两种类型的字段(fields)。
- 第一种是fixed fields,是说field的名称是固定的;
- 第二种是Patterned fields,field的名字不是固定的,而是使用正则表达式匹配。
按照惯例,Swagger规范文件命名为
swagger.json
。另外一个原始数据类型“file”,用于在参数对象或者响应对象中设置参数类型或者响应为一个文件
原始类型有一个可选的属性
format
,Swagger使用了集中常见的格式来对数据类型做更细微的定义。然而,format
属性是一个开放式的string
类型的数据,可以填写任何支持的属性。格式可以是email
、uuid
,甚至可以是一些没有在规范中支持的属性。格式和数据类型并不一定要一致(文件除外),Swagger定义了如下格式名称(Common Name) | 类型(type) | format | 说明 |
integer | integer | int32 | signed 32 bits |
long | integer | int64 | signed 64 bits |
float | number | float | |
double | number | double | |
string | string | | |
byte | string | byte | base64 encoded characters |
binary | string | binary | any sequence of octets |
boolean | boolean | | |
date | string | date | |
dateTime | string | date-time | |
password | string | password | Used to hint UIs the input needs to be obscured. |
Swagger 对象(Swagger Object)
这是API规范的根文档对象。它将以前的资源清单和API声明(版本1.2和早期)合并到一个文档中。
固定字段(Fixed Fields)
字段名称(Field Name) | 类型(Type) | 描述(Description) |
swagger | string | 必需的。指定使用的Swagger 规范版本。它可以Swagger UI和其他客户使用来解释API清单。该值必须是“2.0”。 |
info | 必需的。提供关于API的元数据。如果需要的话,客户端可以使用元数据。 | |
host | string | |
basePath | string | |
schemes | string数组([string]) | 定义API传输的协议。值必须来自列:“http”、“https”、“ws”、“wss”。如果不包指定schemes,默认的scheme就是访问Swagger时访问的协议。 |
consumes | string数组([string]) | |
produces | string数组([string]) | API可生成的MIME类型列表。这对于所有API都是全局的,但可以在特定的API调用上重写。价值必须像Mime Types所描述的那样。 |
paths | 必需的。API的可用路径和操作符。 | |
definitions | 一个对象,用来保存由操作生成和使用的数据类型。 | |
parameters | 可以在整个操作中使用参数的对象。此属性不为所有操作定义全局参数。 | |
responses | 可以在整个操作中使用响应的对象。该属性不定义所有操作的全局响应。 | |
securityDefinitions | 可以跨规范使用的安全性方案定义。 | |
security | 将API应用于整个安全计划的声明。值的列表描述可使用的其他安全方案(也就 是说,有一个逻辑或在安全要求之间)。个别操作可以重写这个定义。 | |
tags | ||
externalDocs | 添加外部文件。 |
通配对象(Patterned Objects)
Field Pattern | Type | Description |
^x- | 任何类型(Any) |
Info对象(Info Object)
该对象提供关于API的元数据。如果需要的话,客户端可以使用元数据,并且可以在Swagger-UI中提供方便。
固定字段(Fixed Fields)
Field Name | Type | Description |
title | string | 必需的。应用程序的标题。 |
description | string | |
termsOfService | string | API的服务条款。 |
contact | API作者联系方式。 | |
license | API的许可证信息。 | |
version | string | 必需的。提供应用程序API的版本(不要与规范版本混淆)。 |
通配对象(Patterned Objects)
字段通配(Field Pattern) | 类型(Type) | 描述(Description) |
^x- | Any |
Info 对象示例:
{
"title": "Swagger Sample App",
"description": "This is a sample server Petstore server.",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"name": "API Support",
"url": "http://www.swagger.io/support",
"email": "[email protected]"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "1.0.1"
}
title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: http://swagger.io/terms/
contact:
name: API Support
url: http://www.swagger.io/support
email: [email protected].io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
Contact 对象(Contact Object)
API的作者联系信息。
固定字段(Fixed Fields)
字段名(Field Name) | 类型(Type) | 描述(Description) |
name | string | 联系人/组织的识别名称。 |
url | string | 指向联系人信息的URL。必须以URL的格式。 |
email | string | 联系人/组织的电子邮件地址。必须以电子邮件地址的格式。 |
通配对象(Patterned Objects)
字段通配(Field Pattern) | 类型(Type) | 描述(Description) |
^x- | Any |
Contact 对象示例:
许可证对象(License Object)
公开API的许可信息。
固定字段(Fixed Fields)
字段名(Field Name) | 类型(Type) | 描述(Description) |
name | string | 必需的。用于API的许可证名称。 |
url | string | 用于API的许可证的URL。必须以URL的格式。 |
| | |
通配对象(Patterned Objects)
字段通配(Field Pattern) | 类型(Type) | 描述(Description) |
^x- | Any |
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
Paths 对象(Paths Object)
通配对象(Patterned Objects)
字段通配(Field Pattern) | 类型(Type) | 描述(Description) |
/{path} | ||
^x- | Any |
Paths 对象示例:
{
"/pets": {
"get": {
"description": "Returns all pets from the system that the user has access to",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "A list of pets.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/pet"
}
}
}
}
}
}
}
/pets:
get:
description: Returns all pets from the system that the user has access to
produces:
- application/json
responses:
'200':
description: A list of pets.
schema:
type: array
items:
$ref: '#/definitions/pet'
Path Item 对象(Path Item Object)
用于描述对于单一Path可以进行的操作。Path Item可以为空,这种情况下,路径仍然会暴露在文档查看器,但是用户并不知道可以进行哪些操作和参数。
固定字段(Fixed Fields)
字段名(Field Name) | 类型(Type) | 描述(Description) |
$ref | string | |
get | 此路径上的GET操作定义 | |
put | 此路径上的POST操作定义 | |
post | 此路径上的PUT操作定义 | |
delete | 此路径上的DELETE操作定义 | |
options | 此路径上的OPTIONS操作定义 | |
head | 此路径上的HEAD操作定义 | |
patch | 此路径上的PATCH操作定义 | |
parameters | 适用于此路径下描述的所有操作的参数列表。这些参数可以在操作级别重写,但不能在那里删除。列表必须不包含重复的参数。一个惟一的参数由名称和位置的组合来定义。该列表可以使用引用对象来链接到Swagger对象的参数中定义的参数。最多可以有一个“body”参数。 |
通配对象(Patterned Objects)
字段通配(Field Pattern) | 类型(Type) | 描述(Description) |
^x- | Any |
Path Item 对象示例
{
"get": {
"description": "Returns pets based on ID",
"summary": "Find pets by ID",
"operationId": "getPetsById",
"produces": [
"application/json",
"text/html"
],
"responses": {
"200": {
"description": "pet response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Pet"
}
}
},
"default": {
"description": "error payload",
"schema": {
"$ref": "#/definitions/ErrorModel"
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of pet to use",
"required": true,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "csv"
}
]
}
get:
description: Returns pets based on ID
summary: Find pets by ID
operationId: getPetsById
produces:
- application/json
- text/html
responses:
'200':
description: pet response
schema:
type: array
items:
$ref: '#/definitions/Pet'
default:
description: error payload
schema:
$ref: '#/definitions/ErrorModel'
parameters:
- name: id
in: path
description: ID of pet to use
required: true
type: array
items:
type: string
collectionFormat: csv
Operation 对象(Operation Object)
描述路径上的一个API操作。
固定字段(Fixed Fields)
字段名(Field Name) | 类型(Type) | 描述(Description) |
tags | [string] | |
summary | string | |
description | string | |
externalDocs | 外部文档对象 | |
operationId | string | |
consumes | [string] | |
produces | [string] | |
parameters | [Parameter 对象数组 | Reference 对象数组] | |
responses | Responses 对象 | |
schemes | [string] | |
deprecated | boolean | |
security | [Security Requirement 对象数组] | |
通配对象(Patterned Objects)
字段通配(Field Pattern) | 类型(Type) | 描述(Description) |
^x- | Any |
Operation 对象示例:
{
"tags": [
"pet"
],
"summary": "Updates a pet in the store with form data",
"description": "",
"operationId": "updatePetWithForm",
"consumes": [
"application/x-www-form-urlencoded"
],
"produces": [
"application/json",
"application/xml"
],
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet that needs to be updated",
"required": true,
"type": "string"
},
{
"name": "name",
"in": "formData",
"description": "Updated name of the pet",
"required": false,
"type": "string"
},
{
"name": "status",
"in": "formData",
"description": "Updated status of the pet",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "Pet updated."
},
"405": {
"description": "Invalid input"
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
tags:
- pet
summary: Updates a pet in the store with form data
description: ""
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
- application/xml
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
type: string
- name: name
in: formData
description: Updated name of the pet
required: false
type: string
- name: status
in: formData
description: Updated status of the pet
required: false
type: string
responses:
'200':
description: Pet updated.
'405':
description: Invalid input
security:
- petstore_auth:
- write:pets
- read:pets
外部文档对象(External Documentation Object)
允许引用外部资源来扩展文档。
固定字段(Fixed Fields)
字段名(Field Name) | 类型(Type) | 描述(Description)urlurl |
description | string | |
url | string | 必须的。目标文档的URL。必须符合URL格式。 |
通配对象(Patterned Objects)
字段通配(Field Pattern) | 类型(Type) | 描述(Description) |
^x- | Any |
外部文档对象示例:
{
"description": "Find more info here",
"url": "https://swagger.io"
}
description: Find more info here
url: https://swagger.io
Parameter 对象(Parameter Object)
描述单个操作参数。
有五种可能的参数类型。
- Query - 添加到URL的参数。例如,在
/items?id=###
,查询参数是id。 - Header - 自定义的请求头参数,作为请求的一部分。
- Body - 附加到HTTP请求的payload。因为只有一个payload,所以只能有一个Body参数。body参数的名称对参数本身没有影响,仅用于文档目的。考虑到Form本身也是一种Body,所以对于同一个操作,Form和Body不能共存。
- Form - 当请求的contentType为
application/x-www-form-urlencoded
或者application/form-data
或者两者都有时(在Swagger的定义中,操作的consumes属性)。用于描述附加在HTTP请求上的payload。这是唯一可以用来发送文件的参数类型,从而支持文件类型。由于在payload中发送了表单参数,因此无法将它们与相同操作的body参数一起声明。表单参数的格式与使用的内容类型有不同(为了进一步的细节,请参考http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
application/x-www-form-urlencoded- 与Query参数格式相似,但是却是一个payload。例如:
foo=1
&
bar=swagger
中,foo和bar都是表单参数。这种格式通常用于简单参数的传输。
multipart/form-data- 每个参数使用一个内部的header单独占一段。例如:
Content-Disposition: form-data; name="submit-name"
,参数的名字是
submit-name
。这种类型的表单多用于文件传输。
固定字段(Fixed Fields)
字段名(Field Name) | 类型(Type) | 描述(Description) |
| | |
| | |