Swagger RESTful API文档规范

*注意编写的关键词：“必须”、“不能”、“须要”、“应当”,“不得”、“应该”、“不该该”,“推荐”、“可能”和“可选的”

原文连接：http://swagger.io/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。 删除一个顶级安全声明,可使用一个空数组。