Swagger2 在spring boot中的運用- API Docs在spring boot中詳細配置生成及各個平臺介面網路請求程式碼生成Swagger-codegen-cli運用
好久沒有寫學習部落格了。在最近的工作中，學習到了一些比較好的工具。可以提高前後臺工作人員，測試人員的工作效率。甚至可以給產品提供相關直觀的參考。也利於版本迭代api的系統管理，現部落格記錄下來，有什麼不足之處請各位大牛指正！
有很多因素促成了Swagger在構建RESTful API方面的快速應用。我們列出了為什麼使用Swagger來設計API的最重要的部分：
同時設計和記錄API，從而保持藍圖和文件同步。
通過自動生成的互動式API文件可以看到實際使用的API，從而實現人機和機器可讀。
圍繞該框架的大型綜合工具生態系統，可讓您超越設計，從SDK生成到測試和除錯。
強大的開源社群支援和領導框架。
下面我們進入正題：
一、Swagger2 在spring boot中的運用（簡單配置）
瞭解一下Swagger：Swagger是全球最大的OpenAPI規範（OAS）API開發工具框架，支援從設計和文件到測試和部署的整個API生命週期的開發。下面我們來進行配置：
首先生成一個最基本的spring boot專案：可以基於maven或者gradle
1、maven：
下載建立好的專案，匯入到開發工具，我這邊使用的是：intellij IDEA
現在配置pom.xml 中swagger配置。2.8.0最新版本（maven springfox 檢視當前使用最多和最新版本）
<!--加上swagger的依賴--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>
2、gradle
build.gradle中新增
compile('io.springfox:springfox-swagger2:2.8.0')
compile('io.springfox:springfox-swagger-ui:2.8.0')配置好以上！下面開始進行真正swagger相關任務。
專案中配置基本的Swagger常規引數：
swagger 基本配置類
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApiDocket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.gt.swaggerfirst.controller")) .build(); } public ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger First Rest Api 文件") .description("user 模組api文件") .version("0.0.1") .termsOfServiceUrl("") .build(); } }
@Configuration spring boot中配置註解，讓Spring來載入該類配置。
@EnableSwagger2 註解來啟用Swagger2。
再通過createRestApiDocket函式建立Docket的Bean之後，apiInfo()用來建立該Api的基本資訊（這些基本資訊會展現在文件頁面中）。select()函式返回一個ApiSelectorBuilder例項用來控制哪些介面暴露給Swagger來展現，本例採用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，併產生文件內容（除了被@ApiIgnore指定的請求）。
啟動專案，輸入請求地址就可以看到swagger已經生效了，目前還沒有相關介面api
swagger簡單配置就是以上內容。
二、下面我們來看具體的api文件相關注解使用。
api介面如圖：
提供便捷的api介面測試：
這邊使用一個User相關的介面為例，先上程式碼結構：
詳細程式碼：
UserController.java
@RestController @RequestMapping(value = "/user") @Api(value = "/user", description = "User 相關操作") public class UserController { @Autowired private UserService userService; @RequestMapping(value = "/login", method = RequestMethod.POST) @ApiOperation(value = "/login", notes = "使用者密碼登入") @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "18888888888", required = true), @ApiImplicitParam(name = "password", value = "88888888", required = true)}) @ApiResponses({@ApiResponse(code = 1000, message = "成功返回碼", response = ResponseResult.class), @ApiResponse(code = 0, message = "失敗返回碼", response = ResponseResult.class)}) public ResponseResult loginByPass(@RequestBody UserEntity userEntity) { ResponseResult responseResult = userService.login(userEntity.getUsername(), userEntity.getPassword()); return responseResult; } }
RestController、RequestMapping Spring boot Restful 註解
| 作用範圍 | API | 使用位置 |
|---|---|---|
| 物件屬性 | @ApiModelProperty | 用在出入引數物件的欄位上 |
| 協議集描述 | @Api | 用於controller類上 |
| 協議描述 | @ApiOperation | 用在controller的方法上 |
| Response集 | @ApiResponses | 用在controller的方法上 |
| Response | @ApiResponse | 用在 @ApiResponses裡邊 |
| 非物件引數集 | @ApiImplicitParams | 用在controller的方法上 |
| 非物件引數描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法裡邊 |
| 描述返回物件的意義 | @ApiModel | 用在返回物件類上 |
對應的每一個註解，其中引數可以參考具體swagger文件！
三、利用swagger-codegen-cli
運用swagger-cli生成對應的請求介面框架程式碼，給開發人員帶來很大的福利，減少重複工作。提高團隊開發效率
由於個人涉及android開發，現以android為例：
1、下載 swagger-codegen-cli-2.2.1.jar，相關用法可以 java -jar swagger-codegen-cli-2.2.1.jar help
命令列打印出幫助說明
usage: swagger-codegen-cli <command> [<args>]
The most commonly used swagger-codegen-cli commands are:
config-help Config help for chosen lang
generate Generate code with chosen lang
help Display help information
langs Shows available langs
meta MetaGenerator. Generator for creating a new template set and configuration for Codegen. The output will be based on the language you specify, and includes default templates to include.
validate Validate specification
version Show version information
See 'swagger-codegen-cli help <command>' for more information on a specific
command.2、生成請求後臺介面的相關框架程式碼，需要兩個配置檔案，
- api介面的相關json，此檔案在swagger配置成功後，生成api是已經生成：；
- 生成android程式碼是config.json配置檔案，檔案中包括：網路請求使用的框架（retrofit2）、Rxjava，包名等；
library，生成的程式碼支付的類，有jersey1、jersey2、okhttp-gson、resttemplate、resteasy、feign、retrofit、retrofit2等幾種型別，我們選擇的retrofit2
developerName，開發者名字，會出現在程式碼檔案裡
developerEmail，開發者郵箱，會出現在程式碼檔案裡
developrOrganization，開發者組織，會出現在程式碼裡
invokerPackage，專案的包名
apiPackage，生成的***Api.java檔案的包名
modelPackage，生成的資料模型java檔案包名
dateLibrary，時間使用的類開
useRxJava，是否使用rxjava生成api介面
useRxJava2，是否使用rxjava2的方式呼叫介面，在這裡我們設為true
本例項中配置json如下：
{"library": "retrofit2",
"useRxJava2": "true",
"developerName": "gt",
"developerEmail": "",
"developerOrganization": "albani.com",
"invokerPackage": "com.gt.app",
"modelPackage": "com.gt.app.data.entity",
"apiPackage": "com.gt.app.data.api",
"artifactId": "swagger-user-retrofit2"
}
生成命令如下：
java -jar swagger-codegen-cli-2.2.1.jar generate -i api.json -o client -l java -c config.json
見證奇蹟的時刻：
生成一個client資料夾，裡面就是相關android的相關介面的請求程式碼：
程式碼結構：
主要程式碼：
UsercontrollerApi.java
public interface UsercontrollerApi { /** * /login * 使用者密碼登入 * @param userEntity userEntity (required) * @return Call<ResponseResult> */ @POST("user/login") Call<ResponseResult> loginByPassUsingPOST( @Body UserEntity userEntity ); }
進行相關調整就可以運用到專案中！
以上內容就是swagger在日常專案中運用到的相關點。
相關原始碼：https://github.com/gutaowqq20081010/Swagger-first
寫的不對，不好的地方請大牛指正！