SpringBoot项目整合Swagger-UI

Swagger-UI动态地根据注解生成在线API文档。

参考文章：

mall整合Swagger-UI实现在线API文档（包含详细的步骤）

mybatis-plus自动生成实体类(包含swagger注解)（因为1中是mybatis的代码生成器，另外找了mybatis-plus的）

常用注解

• @Api：用于修饰Controller类，生成Controller相关文档信息
• @ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
• @ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
• @ApiModel：用于修饰实体类，生成实体相关文档信息
• @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

整合步骤

1. 在pom.xml中添加依赖

2. 配置SwaggerConfig文件

   • 配置Swagger的Docket Bean实例

     .enable(false) 是否启用swagger

     .apis(RequestHandlerSelectors.**basePackage**("watt.gasleakage.controller"))

     RequestHandlerSelectors 配置要扫描接口的方式

     basePackage 指定要扫描的包

     .apis(RequestHandlerSelectors.**withClassAnnotation**(Api.class))

     withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象，如RestController.class

     .apis(RequestHandlerSelectors.**withClassAnnotation**(ApiOperation.class))

     withMethodAnnotation 扫描方法上的注解，GetMapping.class

     .paths(PathSelectors.any())

     过滤什么路径

   • 配置Swagger信息ApiInfo

   @Configuration  // 配置
   @EnableSwagger2 // 开启Swagger
   public class SwaggerConfig {
       @Bean
       public Docket docket() {
           return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
               .build();
       }
       private ApiInfo apiInfo() {
           Contact contact = new Contact("作者", "链接", "邮箱");
           return new ApiInfoBuilder()
               .title("API文档名")
               .description("API文档描述")
               .version("API文档版本")
               .contact(contact)
               .build();
       }
   }
   

3. 修改mybatis-plus代码生成器的生成规则

但是我的项目中使用了DTO，在Swagger中显示请求参数，需要在dto中添加注解。

@ApiModel(value="User对象", description="")

@ApiModelProperty(value = "用户名")

// 全局配置
GlobalConfig gc = new GlobalConfig(); 
gc.setSwagger2(true); //实体属性 Swagger2 注解

具体使用

1. 在Controller类上使用

@Api：用于修饰Controller类，生成Controller相关文档信息

@Api(tags = "AccountController", description = "用户登录注册")
@RestController
public class AccountController {}

2. 在Controller类中方法上使用

@ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息

@ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息

@ApiOperation("用户登录")
@PostMapping("login")
public Result login(@Validated @RequestBody @ApiParam("账号对象") LoginDto loginDto, HttpServletResponse response) {}

3. 在实体类上使用

@ApiModel：用于修饰实体类，生成实体相关文档信息

@Data
@ApiModel(value="User对象", description="")
public class LoginDto implements Serializable {}

4. 在实体类的属性上使用

@ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

@ApiModelProperty(value = "用户名")
private String userName;