Swagger接口文档配置与使用

如何使用Swagger接口文档测试Springboot接口

1、添加依赖

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-spring-web</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2、Controller类添加注解

Controller类上添加注解：@Api(value = “类的说明”)，需要在接口文档中显示的接口上面添加注解：@ApiOperation(value = “接口说明”)，在io.swagger.annotations包下。

3、application配置文件中添加配置

application.yml文件配置如下

swagger:
  default-include-pattern: /.*
  title: com.example.demo
  version: 1.0

如果是application.properties文件配置如下

swagger.default-include-pattern=/.*
swagger.title=com.example.demo
swagger.version= 1.0

com.example.demo是启动类所在目录，在启动类上添加注解@EnableSwagger2，此时Swagger已经配置完成可以访问了，假如项目端口号设置为7777，则Swagger接口文档的访问地址是：
http://localhost:7777/swagger-ui.html#

4、报错No mapping for GET /swagger-ui.html的解决方法

添加配置类

package com.example.demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

/**
 * @description：swagger相关
 * @author： 夏之小星星
 * @create： 2024/4/17 9:12
 */
@Configuration
public class WebMvcConfig  extends WebMvcConfigurerAdapter {
    @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);
    }

}

5、报错"Invalid Token. null"的解决方法

在访问Swagger接口文档测试接口的时候，Response body返回如下信息

{
  "timestamp": "2024-04-17T01:37:25.286+00:00",
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid Token. null",
  "path": "/Test/form1"
}

说明接口调用时没有携带token，需要添加配置给Swagger接口文档添加“Authorize”按钮保存token，才能访问接口。添加方式com.example.demo.config文件夹下添加Swagger配置文件如下：

package com.example.demo.config;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.Contact;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    @Bean
    public Docket docket()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活 《1》
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解 《2》
                //.apis(RequestHandlerSelectors.basePackage("com.maoyou.project.tool.swagger"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                /* 设置安全模式，swagger可以设置访问token */
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：接口文档标题")
                // 描述
                .description("描述：具体描述")
                // 版本
                .version("版本号:0.1" )
                .build();
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<ApiKey> securitySchemes()
    {
        List<ApiKey> apiKeyList = new ArrayList<ApiKey>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts()
    {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth()
    {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

}

添加完配置文件后，Swagger文档会出现“Authorize”按钮，点击按钮添加token数据，再次测试接口，接口访问成功。