springboot整合swagger

概述

• swagger可以方便的生成接口文档，不需要单独书写。
• spring整理swagger简单，编码量低，容易阅读学习。
• 主要步骤：
  1. springboot引入swagger依赖。
  2. 配置swagger。
  3. controller接口上添加注解，标注接口内容。
  4. 查看。

参考资料

《Spring Boot整合swagger使用教程》，作者：随风行云，地址：https://www.cnblogs.com/progor/p/13297904.html

《SpringBoot整合Swagger3.0》，作者：蓝天⊙白云，地址：https://blog.csdn.net/qq_38747892/article/details/125501031

《IDEA报错之Failed to start bean ‘documentationPluginsBootstrapper‘问题及解决方案》，作者：群鸿，地址：https://blog.csdn.net/mapboo/article/details/121568519

解决HttpSession类过滤问题，地址：https://class.m.imooc.com/qadetail?qid=289940

实施步骤

1. 引入swagger依赖

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-spring-web</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
    <!-- A1  -->
    <exclusions>
        <exclusion>
            <artifactId>swagger-models</artifactId>
            <groupId>io.swagger</groupId>
        </exclusion>
    </exclusions>
</dependency>

<!-- A2 -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.6.8</version>
</dependency>

• 代码A1和A2处解决swagger打开页面后自动访问后端接口的问题，改为手动触发。

2. 配置swagger

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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;
import javax.servlet.http.HttpSession;

@Profile("dev") //表明开发环境生效
@Configuration // 标明是配置类
@EnableSwagger2 //开启swagger功能
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // DocumentationType.SWAGGER_2 固定的，代表swagger2
                //.groupName("分布式任务系统") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo()) // 用于生成API信息
                .ignoredParameterTypes(HttpSession.class)//如果参数列表中有 httpSession，在接口文档不显示，这个是过滤指定类 A2
                .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller")) // 用于指定扫描哪个包下的接口
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();
    }

    /**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API") //  可以用来自定义API的主标题
                .description("") // 可以用来描述整体的API
                .termsOfServiceUrl("") // 用于定义服务的域名
                .version("1.0") // 可以用来定义版本。
                .build(); //
    }

}

• Profile注解标明只有在开发环境才起效。
• A2处代码是为了过滤指定类，这里是为了swagger界面中不展示HttpSession参数信息。资料中有@ApiIgnore注解，我没找到。

3. 标注接口组

@Api(tags = "模板管理")
@RestController
@RequestMapping("/pq/device")
public class ModelController {

4. 标注接口

@ApiOperation(value = "获取模板列表")
@GetMapping("/list")
public Result<Page<ModelVO>> findList(@Valid ModelQueryDTO query) {

5. 标注参数，实体

@ApiModel(value="查询模板DTO",description="")
public class ModelQueryDTO

6. 标注参数属性，实体中的属性

@ApiModelProperty(value = "id", required = true, example = "")
private Integer id;

7. 参数不是实体

@ApiOperation(value = "删除模板")
@ApiImplicitParams({
    @ApiImplicitParam(name = "modelId",
            value = "模板id",
            required = true,
            paramType = "query"
    )
})
@GetMapping("/delete")
public Result delete(@NotNull(message = "模板id不能为空") Integer modelId) 

• paramType常用的path,query,body,form,header等方式，但对于对于非实体类参数的时候，常用的只有path,query,header。path是参数在路径上的，query是url中？后面的，header是请求头中的。

8. 返回值如果是实体类也可以仿照第5步和第6步操作。
9. 访问查看，地址：http://localhost:8081/swagger-ui/index.html
   • 这个不同的版本有区别，如果无效可以试试这个：http://localhost:8080/swagger-ui.html
   • 地址中的ip和端口都是整合入工程的ip、端口。

遇到的问题

1. spring整合swagger后报错：Failed to start bean ‘documentationPluginsBootstrapper‘。
   答：原因是spring和swagger版本不兼容导致的。调整版本号，或者添加配置

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2. HttpSession类对象不想显示在swaggerui接口界面上。
   答：配置环境的时候添加过滤，在步骤-第2步中有说明。
3. swagger接口文档只在开发环境生效。
   答：使用@Profile注解。
4. swagger如何关闭自动访问后端接口。
   答：降低swagger-models版本，参考步骤-第1步。