您现在的位置是:首页 >技术交流 >springboot整合swagger网站首页技术交流

springboot整合swagger

田秋浩 2024-06-17 10:19:54
简介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打开页面后自动访问后端接口的问题,改为手动触发。
  1. 配置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注解,我没找到。
  1. 标注接口组
@Api(tags = "模板管理")
@RestController
@RequestMapping("/pq/device")
public class ModelController {
  1. 标注接口
@ApiOperation(value = "获取模板列表")
@GetMapping("/list")
public Result<Page<ModelVO>> findList(@Valid ModelQueryDTO query) {
  1. 标注参数,实体
@ApiModel(value="查询模板DTO",description="")
public class ModelQueryDTO
  1. 标注参数属性,实体中的属性
@ApiModelProperty(value = "id", required = true, example = "")
private Integer id;
  1. 参数不是实体
@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是请求头中的。
  1. 返回值如果是实体类也可以仿照第5步和第6步操作。
  2. 访问查看,地址: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
  1. HttpSession类对象不想显示在swaggerui接口界面上。
    答:配置环境的时候添加过滤,在步骤-第2步中有说明。
  2. swagger接口文档只在开发环境生效。
    答:使用@Profile注解。
  3. swagger如何关闭自动访问后端接口。
    答:降低swagger-models版本,参考步骤-第1步。
风语者!平时喜欢研究各种技术,目前在从事后端开发工作,热爱生活、热爱工作。