swagger系列二：swagger 語法

flyer_dev 發布于2019-06-28 18:38 / 1381人閱讀

摘要：在的下有示例寫法。拿過來分析記錄。官方注解文檔標題部分接口文檔測試文檔項目效果圖接口所支持的協議可以填多種協議主機名或。提供的基本路徑，它是相對于。必須以一個前導斜杠開始是拼接出來的。描述跳轉鏈接聯系開發者，發送郵件。

在swagger-php的Example下有示例寫法。拿過來分析記錄。

swagger官方注解：https://bfanger.nl/swagger-explained/#schemaObject go

1. 文檔標題部分

/**
 * @SWGSwagger(
 *     schemes={"http"},
 *     host="api.com",
 *     basePath="/v1",
 *     @SWGInfo(
 *         version="1.0.0",
 *         title="API接口文檔",
 *         description="測試swagger文檔項目",
 *         @SWGContact(
 *             name="wxp",
 *             email="panxxxx@163.com"
 *         )
 *     ),
 *      @SWGExternalDocumentation(
 *         description="wxp",
 *         url="./"
 *     )
 * )
 */

效果圖：

schemes: 接口所支持的協議 (可以填多種協議)

host：主機名或ip。

basePath：提供API的基本路徑，它是相對于host。必須以一個前導斜杠（/）開始. Base URL 是 host + basePath 拼接出來的。

Info : 文檔描述。

version ：版本號。

title :標題。

description : 描述信息。

ExternalDocumentation":外部文檔鏈接。

description:描述

url :跳轉鏈接

Contact ：聯系開發者，發送郵件。

name : 開發者姓名

email :郵件地址。

2. tag標簽部分，用于文檔分類

/**
 * @SWGTag(
 *   name="pet",
 *   description="你的寵物信息",
 *   @SWGExternalDocumentation(
 *     description="查看更多",
 *     url=""
 *   )
 * )
 * @SWGTag(
 *   name="store",
 *   description="查看寵物店訂單"
 * )
 * @SWGTag(
 *   name="user",
 *   description="用戶操作記錄",
 *   @SWGExternalDocumentation(
 *     description="關于寵物店",
 *     url="http://swagger.io"
 *   )
 * )
 */

name : 名稱(功能模塊)

description : 描述

3. 接口注釋寫法

    /**
     * @SWGGet(
     *     path="/pet/{petId}",
     *     summary="通過ID查詢寵物",
     *     description="返回寵物信息",
     *     operationId="getPetById",
     *     tags={"pet"},
     *     consumes={"application/json", "application/xml"},
     *     produces={"application/xml", "application/json"},
     *     @SWGParameter(
     *         description="ID of pet to return",
     *         in="path",
     *         name="petId",
     *         required=true,
     *         type="integer",
     *         format="int64"
     *     ),
     *     @SWGResponse(
     *         response=200,
     *         description="successful operation",
     *         @SWGSchema(ref="#/definitions/Pet")
     *     ),
     *     @SWGResponse(
     *         response="400",
     *         description="Invalid ID supplied"
     *     ),
     *     @SWGResponse(
     *         response="404",
     *         description="Pet not found"
     *     ),
     *     security={
     *       {"api_key": {}}
     *     }
     * )
     */

Get：請求的 HTTP 方法，支持GET/POST/PUT/DELETE 等 HTTP 標準請求方法

path：請求的路徑

summary：接口簡介，不能超過120個字符

tags：接口標簽，可以是多個

description：接口描述，支持 Markdown 語法

operationId：操作的 ID，全局唯一的接口標識

consumes：接口接收的MIME類型，如 application/json

produces：接口返回的MIME類型,如 application/json

parameters：參數列表

description：參數描述

in：參數從何處來. 必填. 取值僅限: "query", "header", "path", "formData", "body"

name：參數名.

required：參數是否必須. 通過路徑傳參(in 取值 "path")時必須為 true.

type=參數類型. 取值僅限: "string", "number", "integer", "boolean", "array", "file"

format：參數格式，如"int64"

response: 描敘了來自API操作的單個響應

response:返回碼

description=描述

@SWGSchema(ref="#/definitions/Pet")：引用definitions/Pet定義的對象

4. 定義對象 5.type 為array的寫法

GPU云服務器云服務器 swagger swagger+spring 輕量云服務器 swagger 云服務器jar包swagger

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/28495.html

JavaScript 中基于 swagger-decorator 的自動實體類構建與 Swagger

摘要：中基于的自動實體類構建與接口文檔生成是筆者對于開源項目的描述，對于不反感使用注解的項目中利用添加合適的實體類或者接口類注解，從而實現支持嵌套地實體類校驗與生成等模型生成基于的接口文檔生成等等功能。 JavaScript 中基于 swagger-decorator 的自動實體類構建與 Swagger 接口文檔生成是筆者對于開源項目 swagger-decorator 的描述，對于不反感使...

Gemini 2019-08-20 18:06 評論0 收藏0
【效率專精系列】善用API統一描述語言提升RestAPI開發效率

摘要：其標準為前身是，提供強大的在線編輯功能，包括語法高亮錯誤提示自動完成實時預覽，并且支持用戶以格式撰寫導入導出轉換文檔。團隊內部RestAPI開發采用設計驅動開發的模式，即使用API設計文檔解耦前端和后端的開發過程，雙方只在聯調與測試時耦合。在實際開發和與前端合作的過程中，受限于眾多因素的影響，開發效率還有進一步提高的空間。本文的目的是優化工具鏈支持，減少一部分重復和枯燥的勞動。現狀...

tianyu 2019-08-16 10:42 評論0 收藏0
api 接口管理工具

摘要：接口管理工具大致分為線上工具和自建工具。安裝其他工具上面講的，不管是線上工具還是自建工具，都是接口集成工具，主要是為了提供數據功能。類似網易云筆記印象筆記的筆記管理工具。 api 接口管理工具現在，Web 應用的前后端分離事實上已經成為了大家都認可的一種開發方式，前后端分離之后，前端與后端都用接口（api）來溝通，這就需要我們做好 API 接口管理，所以，這次來聊聊 API 接口管理...

marser 2019-08-23 14:43 評論0 收藏0
api 接口管理工具

摘要：接口管理工具大致分為線上工具和自建工具。安裝其他工具上面講的，不管是線上工具還是自建工具，都是接口集成工具，主要是為了提供數據功能。類似網易云筆記印象筆記的筆記管理工具。 api 接口管理工具現在，Web 應用的前后端分離事實上已經成為了大家都認可的一種開發方式，前后端分離之后，前端與后端都用接口（api）來溝通，這就需要我們做好 API 接口管理，所以，這次來聊聊 API 接口管理...

wuyumin 2019-08-16 14:27 評論0 收藏0
swagger系列一：laravel中部署swagger ui

摘要：部署到項目中可以下來也可以下載文件。解壓后把目錄下的目錄拷貝到下下的文件夾中，如新建。訪問修改為自己的項目文件。找到，把修改為自己的，如，再次訪問即可。但是并不存在，需要生成。如放在下的目錄，用于存放文件。 1. 部署swagger ui 到項目中：可以Git下來 git clone https://github.com/swagger-api/swagger-uiv也可以下載zi...

lookSomeone 2019-06-28 18:39 評論0 收藏0