SwaggerEditor：如何编写RESTful API文档

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规范定义定义的数据类型有:

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