|
|
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
:
support@swagger
.
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 对象示例:
{
"name"
:
"API Support"
,
name
:
API
Support
url
:
http
://
www
.
swagger
.
io
/
support
email
:
support@swagger
.
io
许可证对象（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)