目錄
一.整合swagger2
1. 加依賴
<!-- 引入swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2. 寫配置
swagger配置類
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(
// RequestHandlerSelectors.any() // 所有都暴露
RequestHandlerSelectors.basePackage("xx.xx") // 指定包位置
)
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("spring boot示例接口API")
.description("spring boot示例接口API")
.version("1.0.0")
.build();
}
}
WebMvc中加入配置
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
PS: 如果使用的是SpringBoot2最好實現WebMvcConfigurer, 如果采用的是繼承WebMvcConfigurationSupport, 需加入@EnableWebMvc.下一篇筆記會詳解SpringMVC的配置
3. 常用注解：
- @Api()用於類；
表示標識這個類是swagger的資源
- @ApiOperation()用於方法；
表示一個http請求的操作
- @ApiParam()用於方法，參數，字段說明；
表示對參數的添加元數據（說明或是否必填等）
- @ApiModel()用於類
表示對類進行說明，用於參數用實體類接收
- @ApiModelProperty()用於方法，字段
表示對model屬性的說明或者數據操作更改
- @ApiIgnore()用於類，方法，方法參數
表示這個方法或者類被忽略
- @ApiImplicitParam() 用於方法
表示單獨的請求參數
- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam
4. 演示demo
@SpringBootApplication
@RestController
@Api(tags = "測試")
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
@PostMapping("/insert")
@ApiOperation(value = "新增用戶", httpMethod = "POST")
public User insert(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
@GetMapping("/by-id/{id}")
@ApiOperation(value = "根據id查詢用戶", httpMethod = "GET")
public User insert(@PathVariable String id) {
User user = new User();
user.setUsername("test");
user.setPassword("123");
user.setAge(20);
return user;
}
@PostMapping("/login")
@ApiOperation(value = "登陸", httpMethod = "POST")
public User login(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
@Data
@ApiModel("用戶對象")
static class User {
@ApiModelProperty("id")
private String id;
@ApiModelProperty("用戶名")
private String username;
@ApiModelProperty("密碼")
private String password;
@ApiModelProperty("年齡")
private int age;
@ApiModelProperty("性別")
private int sex;
@ApiModelProperty("真實姓名")
private String realName;
@ApiModelProperty("地址")
private String address;
}
}
5. 實際效果
查詢
新增
登錄
可以看到在查詢的時候沒多大問題, 但是新增時用戶ID一般是后台生成, 登錄的話也只需要用戶名和密碼. 顯示過多的參數會導致文檔冗余.前后端分立后也會造成不知道具體傳參的困擾,那swagger的作用就大打折扣
二. 整合swagger2-plus
針對上訴問題的產生, 就引出了今天的主角swagger2-plus, 有了這個工具我們就可以對參數進行分組, 解決上述問題.
1. 加依賴
<!-- 引入swagger2-plus -->
<dependency>
<groupId>cn.weiguangfu</groupId>
<artifactId>springfox-swagger2-plus</artifactId>
<version>2.9.2-1-beta2</version>
</dependency>
swagger2依賴可以刪除, 有這個依賴就行
2. 寫配置
@Configuration
//@EnableSwagger2
@EnableSwagger2Plus
public class SwaggerConfig {
注釋掉@EnableSwagger2改成@EnableSwagger2Plus
swagger.push.enable=true
配置文件中加入以上代碼
3. 實際應用
加入參數分組類
public class SwaggerGroups {
public static class Insert {};
public static class Login{};
}
將對象參數用@ApiRequestInclude分組類
@Data
@ApiModel("用戶對象")
static class User {
@ApiModelProperty("id")
private String id;
@ApiModelProperty("用戶名")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class, SwaggerGroups.Login.class})
private String username;
@ApiModelProperty("密碼")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class, SwaggerGroups.Login.class})
private String password;
@ApiModelProperty("年齡")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private int age;
@ApiModelProperty("性別")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private int sex;
@ApiModelProperty("真實姓名")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private String realName;
@ApiModelProperty("地址")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private String address;
}
控制層類上加入注解@ApiPlus(true)
@SpringBootApplication
@RestController
@Api(tags = "測試")
@ApiPlus(true)
public class SwaggerApplication {
方法上加入對應分組ApiGroup
@PostMapping("/insert")
@ApiGroup(groups = SwaggerGroups.Insert.class)
@ApiOperation(value = "新增用戶", httpMethod = "POST")
public User insert(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
@GetMapping("/by-id/{id}")
@ApiOperation(value = "根據id查詢用戶", httpMethod = "GET")
public User insert(@PathVariable String id) {
User user = new User();
user.setUsername("test");
user.setPassword("123");
user.setAge(20);
return user;
}
@PostMapping("/login")
@ApiGroup(groups = SwaggerGroups.Login.class)
@ApiOperation(value = "登陸", httpMethod = "POST")
public User login(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
4. 最終效果
可以看到新增接口中id不見了, 登錄也只剩下用戶名和密碼
新增
登錄
