spring-boot项目整合swagger文档

tips：后面还会为工程植入更多的组件，大家看完请帮忙三连~~谢谢大家，后续大家也可以将本工程保存为骨架工程使用。或者大家有什么想要看的组件集成也可以私信我，谢谢~~~

swagger文档目前应用也是很广泛的，本期为大家介绍spring-boot项目整合swagger文档

本着学习的心态我们整合比较新的swagger3，在实际项目中遇到的还是以swagger2为主。本期工程还是接上期整合完mybatis的工程。

swagger文档的整合大致分为三步

1.添加swagger的依赖

2.在yml配置文件中配置swagger所需的配置

3.添加swagger所需的config配置类

接下来我们一步一步来

1.添加依赖

swagger3的依赖如下

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

可以看出swagger3的依赖相对之前版本简化了很多

2.添加yml配置（我直接把所有配置贴出来，大家可以对比了看看）

server:
  port: 8080

spring:
  application:
    name: demo
  datasource:
    username: root
    url: jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=utf-8
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis:
  mapper-locations: classpath:mybatis-mappers/*.xml
  type-aliases-package: com.hw.springbootmybatisxml.entity

swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: 1.0
  application-description: springfox swagger
  try-host: http://localhost:${server.port}

3.添加config配置类。配置类分为两个

SwaggerProperties.class

package com.example.demo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * @author 86186
 */

@Component
@ConfigurationProperties("swagger")
@Data
public class SwaggerProperties {
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
     */
    private Boolean enable;

    /**
     * 项目应用名
     */
    private String applicationName;

    /**
     * 项目版本信息
     */
    private String applicationVersion;

    /**
     * 项目描述信息
     */
    private String applicationDescription;

    /**
     * 接口调试地址
     */
    private String tryHost;


}

SwaggerConfiguration.class

package com.example.demo.config;

import io.swagger.models.auth.In;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.lang.reflect.Field;
import java.util.*;

/**
 * @author 86186
 */
@Configuration
public class SwaggerConfiguration implements WebMvcConfigurer {
    private final SwaggerProperties swaggerProperties;

    public SwaggerConfiguration(SwaggerProperties swaggerProperties) {
        this.swaggerProperties = swaggerProperties;
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")

                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(swaggerProperties.getEnable())

                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())

                // 接口调试地址
                .host(swaggerProperties.getTryHost())

                // 选择哪些接口作为swagger的doc发布
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()

                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http"))

                // 授权信息设置，必要的header token等认证信息
                .securitySchemes(securitySchemes())

                // 授权信息全局应用
                .securityContexts(securityContexts());
    }

    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
                .description(swaggerProperties.getApplicationDescription())
                .contact(new Contact("users", null, "734796109@qq.com"))
                .version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
                .build();
    }

    /**
     * 设置授权信息
     */
    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                        .build()
        );
    }

    @SafeVarargs
    private final <T> Set<T> newHashSet(T... ts) {
        if (ts.length > 0) {
            return new LinkedHashSet<>(Arrays.asList(ts));
        }
        return null;
    }

    /**
     * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
     */
    @SuppressWarnings("unchecked")
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null) {
                for (InterceptorRegistration interceptorRegistration : registrations) {
                    interceptorRegistration
                            .excludePathPatterns("/swagger**/**")
                            .excludePathPatterns("/webjars/**")
                            .excludePathPatterns("/v3/**")
                            .excludePathPatterns("/doc.html");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

以上配置完成之后在spring-boot启动类中新增两个注解

@EnableOpenApi
@EnableWebMvc

之后尝试启动项目，启动完成之后登陆地址http://localhost:8080/swagger-ui/index.html#/，进入如下页面，表示swagger已经整合成功。

整合完成之后，我们尝试使用一下swagger文档的功能。

我们新建一个接口类，并新建一个controller集成这个接口类，并实现接口类中的方法。

 SwaggerApi.class

package com.example.demo.api;

import com.example.demo.api.request.SwaggerApiRequest;
import com.example.demo.api.response.SwaggerApiResponse;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;

/**
 * @author 86186
 */
@RequestMapping("/swagger-test")
@Api(tags = "swagger测试api")
public interface SwaggerApi {

    @GetMapping("/swaggerTest")
    @ApiOperation(value = "swagger文档测试接口", notes = "测试")
    SwaggerApiResponse swaggerTest(SwaggerApiRequest request);

}

SwaggerAipController.class

package com.example.demo.controller;

import com.example.demo.api.SwaggerApi;
import com.example.demo.api.request.SwaggerApiRequest;
import com.example.demo.api.response.SwaggerApiResponse;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 86186
 */
@RestController
public class SwaggerAipController implements SwaggerApi {
    @Override
    public SwaggerApiResponse swaggerTest(SwaggerApiRequest request) {
        SwaggerApiResponse response = new SwaggerApiResponse();
        response.setTest1("1");
        response.setTest2("2");
        response.setTest3("3");
        return response;
    }
}

完成之后启动项目，可以看到该接口再swagger上面的接口文档

 填写参数，点击两个按钮就能测试接口