SpringBoot整合Swagger3

前言

本文将介绍下API可视化框架Swagger在SpringBoot框架中的整合流程，对Swagger3进行测试的一系列内容。

开发背景

若项目是使用前后端分离的方式来开发的，前后端代码的开发就需要开发员进行分工协作，以及进行前后端联调，开发时必须规范开发接口。接口文档的编写工作通常由后端开发员完成，接口文档中包含接口说明、请求URL、请求参数、请求方法、响应数据说明这五个部分。但手动编写接口文档是非常棘手的，所以，接下来我们可以使用Swagger来编写接口文档。

Swagger是什么？（官网）

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。Swagger是⼀个⽤于⽣成服务器接⼝的规范性⽂档、并且能够对接⼝进⾏测试的⼯具。

spring boot集成swagger3版本

• 引入pom.xml依赖

          <dependency>
              <groupId>io.springfox</groupId>
              <artifactId>springfox-boot-starter</artifactId>
              <version>3.0.0</version>
          </dependency>
          <dependency>
              <groupId>com.github.xiaoymin</groupId>
              <artifactId>knife4j-spring-boot-starter</artifactId>
              <version>3.0.3</version>
          </dependency>
  

• 添加swagger3.0配置

package com.weh.config;

import com.google.common.collect.Sets;
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 springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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.Collections;
import java.util.List;

@Configuration
@EnableOpenApi //注意：这个注解是重点
public class SwaggerConfig {
    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(" Api Doc")
                .description("SpringFox 3.0.0 发布: https://www.xx.xx/swagger-ui/index.html")
                .contact(new Contact("weh", null, "xxxxx"))
                .version(
                        "Application Version: "
                                + "1.0.0"
                                + ", Spring Boot Version: "
                                + SpringBootVersion.getVersion())
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")
                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(true)
                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())
                // 接口调试地址
                .host("http://localhost:9098")
                // 选择哪些接口作为swagger的doc发布
                .select()
                // 关键部分：扫描包的路径
                .apis(RequestHandlerSelectors.basePackage("com.weh.controller"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(Sets.newHashSet("http", "https"))
                // 授权信息设置，必要的header token等认证信息
                .securitySchemes(securitySchemes())
                // 授权信息全局应用
                .securityContexts(securityContexts());
    }

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

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

    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();
        }
    }
}

• # 应用服务 WEB 访问端口
  server:
    port: 9098
  

• 整体框架

访问网址：http://localhost:9098/doc.html
页面展示结果：