*注意编写的关键词:“必须”、“不能”、“需要”、“应当”,“不得”、“应该”、“不应该”,“推荐”、“可能”和“可选的”
原文链接:http:///specification/
介绍:
swagger是一个用于描述项目和文档RESTful api。
这里的规范定义了一组描述一个API所需的文件格式。 Swagger-UI项目所使用的这些文件可以显示API和Swagger-Codegen生成客户在不同的语言。 额外的工具也可以利用生成的文件,比如测试工具。
定义
路径模板
路径模板指的是使用大括号({ })URL路径的部分标记为可更换使用路径参数。
Mime类型
Mime类型定义分布在多个资源。 mime类型定义应符合RFC 6838。
一些例子可能的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状态代码是用来指示执行操作的状态。 描述可用的状态码RFC 7231而在IANA状态代码注册表。
规范
格式
描述RESTful API的文件按照大摇大摆规范表示为JSON对象和符合JSON标准。 YAML是JSON的超集,也可以使用 代表的规范文件。
例如,如果一个领域据说数组值,将使用JSON数组表示:
{
"field" : [...]
}
尽管使用JSON API描述它不强加一个JSON API本身输入/输出。
规范中的所有字段名称区分大小写的。
模式暴露了两种类型的字段。 固定字段,声明的名字,和有图案的字段,字段名称声明一个正则表达式模式。 的字段可以有多次出现,只要每个人都有一个惟一名称。
文件结构
的狂妄表示API是由单个文件。 然而,部分的定义可以分为单独的文件中,在用户的自由裁量权。 这是适用于$ref 字段的规范如下JSON模式定义。
按照惯例,大摇大摆规范文件命名swagger.json 。
数据类型
原始数据类型大摇大摆规范中基于支持的类型JSON-Schema草案4。 模型是描述使用模式对象这是一个子集的JSON模式草案4。
一个额外的原始数据类型"file" 使用参数对象和响应对象设置参数类型或响应作为一个文件。
原语有一个可选的修饰符属性format 。 大摇大摆使用几个已知的格式更精确定义所使用的数据类型。 然而,format 房地产是一个开放的string 价值属性,并且可以支持文档需要有任何价值。 格式如"email" ,"uuid" 等,可以使用,即使他们不是由该规范定义的。 类型不伴随着format 属性遵循它们的定义从JSON模式(除了file 上面的类型定义)。 定义的格式的规范有:
普通的名字 | type | format | 说明 |
integer |
integer |
int32 |
签署了32位 |
long |
integer |
int64 |
签署了64位 |
float |
number |
float |
|
double |
number |
double |
|
string |
string |
|
|
byte |
string |
byte |
base64编码的字符 |
binary |
string |
binary |
任何的八位字节序列 |
boolean |
boolean |
|
|
date |
string |
date |
所定义的full-date - - - - - -RFC3339 |
dateTime |
string |
date-time |
所定义的date-time - - - - - -RFC3339 |
password |
string |
password |
用来提示用户界面输入需要模糊。 |
模式
这是一根文档对象的API规范。 它结合了以前是什么资源清单和API声明(1.2和更早的版本)到一个文档。
固定的字段
字段名 | 类型 | 描述 |
swagger |
string |
必需的。使用指定的规范版本。 可以用它大摇大摆的UI和其他客户解释API清单。 的值必须"2.0" 。 |
info |
Info Object |
必需的。提供元数据API。 可以使用元数据的客户如果需要。 |
host |
string |
主机名或ip服务API。 这一定是主机,不包括计划和sub-paths。 这可能包括一个港口。 如果host 不包括,使用主机服务文档(包括港口)。 的host 不支持路径模板。 |
basePath |
string |
API的基本路径,这是相对的host 。 如果不包括,API是直属host 。 必须从价值领先斜杠(/ )。 的basePath 不支持路径模板。 |
schemes |
[string ] |
API的传输协议。 值必须从列表中:"http" ,"https" ,"ws" ,"wss" 。 如果schemes 不包括,默认使用计划是用于访问大摇大摆的定义本身。 |
consumes |
[string ] |
一个MIME类型的api可以使用列表。 这是可以覆盖全球所有API,但在特定的API调用。 值必须是所描述的Mime类型。 |
produces |
[string ] |
MIME类型的api可以产生的列表。 这是可以覆盖全球所有API,但在特定的API调用。 值必须是所描述的Mime类型。 |
paths |
路径对象 |
必需的。可用的路径和操作的API。 |
definitions |
定义对象 |
一个对象数据类型生产和使用操作。 |
parameters |
参数定义对象 |
一个对象来保存参数,可以使用在操作。 这个属性不为所有操作定义全局参数。 |
responses |
反应定义对象 |
一个对象响应,可以跨操作使用。 这个属性不为所有操作定义全球响应。 |
securityDefinitions |
安全定义对象 |
安全方案定义规范,可以使用。 |
security |
(安全需求对象] |
声明的安全计划申请API作为一个整体。 值的列表描述替代安全方案,可以使用(也就是说,有一个逻辑或安全需求之间)。 个人业务可以覆盖这个定义。 |
tags |
(标签对象] |
的列表标签使用的规范与额外的元数据。 标签的顺序可以用来反思他们的订单的解析工具。 并不是所有使用的标签操作对象必须声明。 声明的标签不可能组织随机或基于工具的逻辑。 列表中的每个标记名称必须是唯一的。 |
externalDocs |
外部文档对象 |
额外的外部文档。 |
固定的字段
字段名 | 类型 | 描述 |
tags |
(string ] |
的标签列表API文档控制。 标签可用于逻辑分组业务的资源或任何其他限定符。 |
summary |
string |
什么操作的一个简短的总结。 最大swagger-ui可读性,这一领域应小于120个字符。 |
description |
string |
详细解释操作的行为。GFM语法可用于富文本表示。 |
externalDocs |
外部文档对象 |
额外的外部文档操作。 |
operationId |
string |
独特的字符串用于识别操作。 id必须是唯一的在所有业务中所描述的API。 工具和库可以使用operationId来唯一地标识一个操作,因此,建议遵循通用的编程的命名约定。 |
consumes |
[string ] |
MIME类型的列表操作可以使用。 这将覆盖consumes 定义在炫耀的对象。 空值可用于全球定义清楚。 值必须是所描述的Mime类型。 |
produces |
[string ] |
MIME类型的列表操作可以产生。 这将覆盖produces 定义在炫耀的对象。 空值可用于全球定义清楚。 值必须是所描述的Mime类型。 |
parameters |
(参数对象 |引用对象] |
适用于该操作的参数列表。 如果已经定义了一个参数道路项目新定义将覆盖它,但不能删除它。 必须不包含重复的参数列表。 一个独特的参数定义的组合的名字和位置。 可以使用列表引用对象链接到参数的定义的对象的参数。 可以有一个“身体”参数。 |
responses |
响应对象 |
必需的。返回的列表可能的反应,因为他们执行这个操作。 |
schemes |
[string ] |
传输协议的操作。 值必须从列表中:"http" ,"https" ,"ws" ,"wss" 。 的值将覆盖的对象schemes 定义。 |
deprecated |
boolean |
声明该操作被弃用。 使用声明的操作应该没有。 默认值是false 。 |
security |
(安全需求对象] |
声明的安全计划申请这个操作。 值的列表描述替代安全方案,可以使用(也就是说,有一个逻辑或安全需求之间)。 这个定义覆盖任何宣布顶级security 。 删除一个顶级安全声明,可以使用一个空数组。 |
|