SwaggerEditor：如何编写RESTful API文档

Posted 2022-07-31 chszs

SwaggerEditor：如何编写RESTful API文档

• 2019.12.17

一、概述

Swagger/OpenAPI规范的目标是为RESTful API的开发定义一个标准的，与语言无关的接口。使用浏览器打开Swagger Editor在线编辑器，就可以按照OpenAPI v3.0.2规范开始编写RESTful API文档了。

1.1、格式

遵循OpenAPI规范的OpenAPI文档本身就是一个JSON对象，可以用JSON格式或YAML格式表示。描述RESTful API的文件可以保存为.json、.yaml、.yml格式。

1.2、数据类型

OpenAPI规范定义定义的数据类型有:

原始类型	类型	格式	说明
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	由RFC-3339规范的full-date定义
dateTime	string	date-time	由RFC-3339规范的date-time定义
password	string	password	UI提示隐藏输入

二、API写法说明

1、第一级标签

可以把OpenAPI文档看成是一个树形结构，第一级的标签有：

• openapi：文档对象，定义文档采用的规范的版本
• info：定义了该API文档相关的元数据信息
• externalDocs：定义文档可以引用的外部资源，以便扩展文档。
• servers：定义实现了API文档的服务器资源
• tags：定义要CRUD操作的资源对象
• paths：定义资源端点的路由路径，以及对资源端点可用的操作，是API文档最重要的内容。
• components：定义了OpenAPI规范文档中使用的一套可重用的、针对不同方面的对象。

2、第二级标签：components

• schemas：用于定义输入和输出的数据类型。这些类型可以是对象，还可以是原始类型或数组类型。
• securitySchemas：定义API操作所使用的安全模式。支持的安全模式有HTTP身份认证、API key（可以作为HTTP头部的内容，或者Cookie参数，或作为查询参数）、OAuth2’s common flows等。

schemas细节

• 实体Bean名/HTTP资源名(首字母大写)
• • type：类型，通常是object
• • properties：属性/成员字段
• • • 属性名/成员字段名
• • • • type：使用(1.2、数据类型)，比如integer
• • • • format：使用(1.2、数据类型)，比如int64
• • • • description：描述，通常省略，关键内容才加上
• • • • default：默认值

3、第二级标签：paths

• 请求的资源路径，也即接口，比如’/folders/folderId’

• • get：请求的HTTP方法，还可以是post、put、delete
• • tags：接口标签，可以有多个
• • summary: 接口简介，不能超过120个字符
• • description：接口描述，支持Markdown语法
• • operationId：操作的ID，全局唯一的接口标识，通常使用Java对应的方法名
• • parameters：参数列表
• • • in：参数从何处来。必填。取值仅限: “query”, “header”, “path”, “formData”, “body”
• • • name：参数名。
• • • description：参数描述
• • • required：参数是否必须。通过路径传参(in取值"path")时reqquired值为true
• • • schema：
• • • • type：参数类型。取值仅限: “string”, “number”, “integer”, “boolean”, “array”, “file”
• • • • format：参数格式，如"int64"
• • requestBody：请求主体
• • • description：请求主体描述
• • • content：
• • • application/json：请求的内容类型，也可能是application/x-www-form-urlencoded
• • • • schema：
• • • • • properties：
• • • • • • name：
• • • • • • • type：类型
• • • • • • • description：描述
• • responses: 描述来自API操作的响应
• • • 响应状态码，比如’404’
• • • • description: 响应描述
• • • • content: 内容