springboot系列十三、springboot整合swaggerUI
一、Swagger介紹
Swagger能成為最受歡迎的REST APIs文件生成工具之一，有以下幾個原因：
- Swagger 可以生成一個具有互動性的API控制檯，開發者可以用來快速學習和嘗試API。
- Swagger 可以生成客戶端SDK程式碼用於各種不同的平臺上的實現。
- Swagger 檔案可以在許多不同的平臺上從程式碼註釋中自動生成。
- Swagger 有一個強大的社群，裡面有許多強悍的貢獻者。
Swagger 文件提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 names、order 等 API 資訊。
你可以通過一個文字編輯器來編輯 Swagger 檔案，或者你也可以從你的程式碼註釋中自動生成。各種工具都可以使用 Swagger 檔案來生成互動的 API 文件。
二、配置及使用Swagger
1、引入依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
2、新增配置類：SwaggerConfig.java
package com.example.demo.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * Swagger2配置類 * 在與spring boot整合時，放在與Application.java同級的目錄下。 * 通過@Configuration註解，讓Spring來載入該類配置。 * 再通過@EnableSwagger2註解來啟用Swagger2。 */ @Configuration @EnableSwagger2 public class SwaggerConfig { /** * 建立API應用 * apiInfo() 增加API相關資訊 * 通過select()函式返回一個ApiSelectorBuilder例項,用來控制哪些介面暴露給Swagger來展現， * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。 * * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo")) .paths(PathSelectors.any()) .build(); } /** * 建立該API的基本資訊（這些基本資訊會展現在文件頁面中） * 訪問地址：http://專案實際地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2構建RESTful APIs") .description("更多請關注:部落格園小人物的奮鬥") .termsOfServiceUrl("http://www.cnblogs.com/wangzhuxing") .contact("xing") .version("1.0") .build(); } }
3、使用示例
1、註解Controller類
@Controller @RequestMapping("/User") @Api(description = "測試swagger註解的demo") public class HelloWorldController {
@ResponseBody
@RequestMapping(value = "/getAllUser" ,method = RequestMethod.POST)
@ApiOperation(value = "獲取使用者資訊",notes = "返回單個使用者資訊")
public List<UserPO> getAllUser(@ApiParam(required = false) @RequestBody User user) {
userService.addUser();
return userService.findAll();
}
}
2、註解入參和出參
package com.example.demo.bean; import io.swagger.annotations.ApiModelProperty; import java.io.Serializable; public class User implements Serializable { @ApiModelProperty(value = "使用者id" ,example = "11") private Long uid; @ApiModelProperty(value = "使用者姓名",example = "小明") private String name; @ApiModelProperty(value = "使用者年齡",example = "25") private Integer age; public Long getUid() { return uid; } public void setUid(Long uid) { this.uid = uid; } public String getName() { return name; } public void setName(String name) { this.name = name; } public Integer getAge() { return age; } public void setAge(Integer age) { this.age = age; } }
4、驗證效果
訪問：http://192.168.1.100:8080/swagger-ui.html
三、常見用法和說明
- @Api：用在類上，說明該類的作用。
- @ApiOperation：註解來給API增加方法說明。
- @ApiImplicitParams : 用在方法上包含一組引數說明。
- @ApiImplicitParam：用來註解來給方法入參增加說明。
- @ApiResponses：用於表示一組響應
-
@ApiModel：描述一個Model的資訊（一般用在請求引數無法使用@ApiImplicitParam註解進行描述的時候）
l @ApiModelProperty：描述一個model的屬性
- @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
l code：數字，例如400
l message：資訊，例如"請求引數沒填好"
l response：丟擲異常的類
Swagger是一組開源專案，其中主要要專案如下：
1. Swagger-tools:提供各種與Swagger進行整合和互動的工具。例如模式檢驗、Swagger 1.2文件轉換成Swagger 2.0文件等功能。
2. Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行整合。
3. Swagger-js: 用於JavaScript的Swagger實現。
4. Swagger-node-express: Swagger模組，用於node.js的Express web應用框架。
5. Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger相容API動態生成優雅文件。
6. Swagger-codegen：一個模板驅動引擎，通過分析使用者Swagger資源宣告以各種語言生成客戶端程式碼。