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規範定義定義的數據類型有:

原始類型	類型	格式	說明
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: 內容