SpringBoot集成Swagger

1、导包

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

2、配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用swagger
                .enable(true)
                // swagger信息
                .apiInfo(apiInfo())
                .select()
                // swagger要扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.haiot.dm.controller"))
                // 扫描过滤规则
                .paths(PathSelectors.any())
                .build();
    }

    // api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("SpringBoot 集成 Swagger")
                //描述
                .description("用于测试 SpringBoot 集成 Swagger")
                //版本号
                .version("1.0")
                .build();
    }
}

3、使用@EnableSwagger2注解修饰启动类

4、使用注解修饰controller层以及其中的方法，常用注解如下：

• @Api：作用在类上，用于说明该类的作用。通常标记一个Controller类作为Swagger文档资源。

@RestController
@Api(tags="管理端-设备消息管理")
public class MessageController {

}

• @ApiOperation：作用在方法上，用于说明该方法的作用。通常用于标记Controller中的方法。

@ApiOperation("删除一条事件")
@GetMapping("deleteOneMsg")
public ServerResponse deleteOneMsg(Integer eventId) {

}

• @ApiImplicitParams：作用在方法上，包含一组参数的说明，用于说明接口请求参数的意义。
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 。
  • paramType：参数放在哪个地方
  • name：参数代表的含义
  • value：参数名称
  • dataType：参数类型
  • required：是否必要，默认false
  • defaultValue：参数的默认值

@ApiOperation(value = "发送简单邮件")
@GetMapping("sendSimpleMail")
@ApiImplicitParams({
        @ApiImplicitParam(name = "to", value = "收件人"),
        @ApiImplicitParam(name = "subject", value = "邮件主题"),
        @ApiImplicitParam(name = "text", value = "邮件内容")
})
private void sendSimpleMail(String to, String subject, String text) throws AddressException {
    emailService.sendSimpleMail(to, subject, text);
}

• @ApiModel：作用在实体类上，用于描述一个Model的信息。这个注解一般用在post请求时，因参数被@RequestBody修饰，请求参数无法使用@ApiImplicitParam注解进行描述的时候；
• @ApiModelProperty：作用在实体类的属性上，用于描述model的某个属性。

@Data
@ApiModel
public class MailMessageVO {
    @ApiModelProperty(value = "收件人")
    private String to;              // 收件人
    @ApiModelProperty(value = "主题")
    private String subject;         // 主题
    @ApiModelProperty(value = "项目名")
    private String projectName;     // 项目名
    @ApiModelProperty(value = "事项类型")
    private String eventItemType;   // 事项类型
    @ApiModelProperty(value = "报错位置")
    private String errorPosition;   // 报错位置
    @ApiModelProperty(value = "报错原因")
    private String errorReason;     // 报错原因
    @ApiModelProperty(value = "报错描述")
    private String errorDescribe;   // 报错描述
}

5、 遇到的小坑之swagger页面资源读取不到？

  看了好久博客说，需要配置过滤器，允许swagger-ui资源被读取，但还是没有用。

  离谱的是，前一天配置了swagger2.9.2与springboot2.5.6死活从swagger2.5.0版本变不过来，明明依赖已经刷新了，显示的也是2.9.2，就算配置了过滤器也无法正常展示，但是关机之后第二天重新启动项目就没有问题了。 想看看是否是过滤器起了作用，所以注释了过滤器类，但是效果依然在，那为什么昨天就不行呢？万能的重启大法啊！

  所以之后配置swagger2.9.2再遇到这种问题的话，可以这么解决：

1、关机，重新启动项目（关掉idea似乎不太行），不行的话换下面的方法

2、配置过滤器类，然后重新启动项目，如果没有生效，则关机再重新启动项目

@Configuration

public class Config extends WebMvcConfigurationSupport {

    @Override

    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("/**").addResourceLocations(

                "classpath:/static/");



        registry.addResourceHandler("swagger-ui.html").addResourceLocations(

                "classpath:/META-INF/resources/");



        registry.addResourceHandler("/webjars/**").addResourceLocations(

                "classpath:/META-INF/resources/webjars/");



        super.addResourceHandlers(registry);

    }

}