SwaggerEditor：如何编写RESTful API文档

雨点打透心脏的1/2处 2023-06-23 04:55 20阅读 0赞

# SwaggerEditor：如何编写RESTful API文档 #

*  2019.12.17

## 一、概述 ##

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

### 1.1、格式 ###

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

### 1.2、数据类型 ###

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

<table> 
 <thead> 
  <tr> 
   <th>原始类型</th> 
   <th align="center">类型</th> 
   <th align="right">格式</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>integer</td> 
   <td align="center"><code>integer</code></td> 
   <td align="right"><code>int32</code></td> 
   <td>带符号32位整数</td> 
  </tr> 
  <tr> 
   <td>long</td> 
   <td align="center"><code>integer</code></td> 
   <td align="right"><code>int64</code></td> 
   <td>带符号64位整数（长整型）</td> 
  </tr> 
  <tr> 
   <td>float</td> 
   <td align="center"><code>number</code></td> 
   <td align="right"><code>float</code></td> 
   <td>浮点数类型</td> 
  </tr> 
  <tr> 
   <td>double</td> 
   <td align="center"><code>number</code></td> 
   <td align="right"><code>double</code></td> 
   <td>双精度浮点数类型</td> 
  </tr> 
  <tr> 
   <td>string</td> 
   <td align="center"><code>string</code></td> 
   <td align="right"></td> 
   <td>字符串类型</td> 
  </tr> 
  <tr> 
   <td>byte</td> 
   <td align="center"><code>string</code></td> 
   <td align="right"><code>byte</code></td> 
   <td>BASE64编码的字符</td> 
  </tr> 
  <tr> 
   <td>binary</td> 
   <td align="center"><code>string</code></td> 
   <td align="right"><code>binary</code></td> 
   <td>任意八位字节的序列</td> 
  </tr> 
  <tr> 
   <td>boolean</td> 
   <td align="center"><code>boolean</code></td> 
   <td align="right"></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>date</td> 
   <td align="center"><code>string</code></td> 
   <td align="right"><code>date</code></td> 
   <td>由<a href="https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14" rel="nofollow">RFC-3339规范</a>的full-date定义</td> 
  </tr> 
  <tr> 
   <td>dateTime</td> 
   <td align="center"><code>string</code></td> 
   <td align="right"><code>date-time</code></td> 
   <td>由<a href="https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14" rel="nofollow">RFC-3339规范</a>的date-time定义</td> 
  </tr> 
  <tr> 
   <td>password</td> 
   <td align="center"><code>string</code></td> 
   <td align="right"><code>password</code></td> 
   <td>UI提示隐藏输入</td> 
  </tr> 
 </tbody> 
</table>

## 二、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: 内容

[Swagger Editor]: http://editor.swagger.io/
[OpenAPI v3.0.2]: https://swagger.io/specification/