Swagger框架學習

1.Swagger的定義

Swagger 是一個規范和完整的API文檔對接框架，通過設置對應的注解，掃描相關的代碼來生成描述文件，進而生成與代碼和對應代碼描述一致并且是可視化 RESTful 風格可以傳入不同參數進行調用的接口文檔。這種通過代碼生成的接口文檔，由于是通過對應注解生成和代碼保持一致，所以在持續迭代的項目中無論如何修改參數方法，接口文檔都會對應作出相同的修改，這使得接口文檔變得具有實時性并且能夠非常高效的傳遞項目中的接口的實際情況。

1.1 Swagger官網也提供了如下幾種開源工具，可以集成配置達到所需求的效果：

Swagger Codegen: 可以將描述文件生成html格式和cwiki形式的接口文檔，同時也能生成多鐘語言的服務端和客戶端的代碼。

Swagger UI:提供了一個可視化的UI頁面展示描述文件，可以直觀的對添加swagger注解的接口進行查詢，參數調用，查看回調結果等一系列操作。

Swagger Editor: 編輯器的編輯Swagger描述文件的編輯器，提供了在線編輯器和本地部署編輯器兩種方式并且可以實時預覽描述文件。

Swagger Inspector:用于Swagger文檔的在線調用調試，相對于Swagger Ui中的調試，會返回更多的信息并且可以保存你請求的實際請求參數等信息。

Swagger Hub：集成了上面所有項目的各個功能可以以項目和版本為單位，將描述文件上傳到Swagger Hub中，相當于一個整合平臺。

2.Swagger的使用

2.1 添加Maven依賴

io.springfox springfox-swagger2 XXX io.springfox springfox-swagger-ui XXX com.github.xiaoymin swagger-bootstrap-ui XXX

在生成swagger文檔時，如何和代碼保持一致，其實就是通過設置的各種注解來實現的。

@Api注解是對請求類的說明，一般常用參數有：

tags：用于描述這個請求類，并且標識這個請求類的情況，標記可用于按資源或任何其他限定符對操作進行邏輯分組；

value：在未使用tags的情況下將用于為這個類的描述情況標記，如果有tags的設置，則該值將被忽略。

@ApiOperation注解是對需要展示接口的標記，常用參數有；

value：提此供接口的簡要描述或者操作說明；

notes：對該接口操作的詳細描述說明。

@ApiResponse注解描述該接口的返回值詳細情況，常用的參數有：

code：返回成功的成功數字標識；

message：返回成功的描述；

response:描述返回值中的響應類的類型。

@RequestParm注解是描述該接口的請求的參數。

@Api(tags="具體controller描述") @RestController public class TestController { @GetMapping("/test") @ApiOperation("具體方法的描述") @ApiResponse(code=0,message="查詢成功",response=XXX.class) public String test(@RequestParam String parm){ ... ... } }

API

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。