swagger实现在线接口文档

一、前言

之前换了新的单位后，单位的项目有使用到swagger，那个时候觉得这个好方便，后面是建立在他们搭建好的基础上使用一些swagger的注解，但一直想要自己去实现，奈何没有机会，这次机会终于来了，完成从0开始，虽然说这个不难，但之前自己没有搭建过，还是遇到了一点问题，好在站在了巨人的肩膀上把问题解决了。

当然如果不使用swagger也可以直接在word中编写接口文档，接口文档主要是给产品，测试，前端看的，由后端同学去维护。

二、本次的参考博客

https://blog.csdn.net/hlx20080808/article/details/120204111
NPE问题的解决

感谢大神！感兴趣的也去看下第一篇文档，第二篇是解决问题的。

三、swagger接口文档

前提条件：我使用的springboot的版本是2.7.7，jdk版本是11

3.1 SpringFox介绍

我这里使用的是SpringFox，它是 spring 社区维护的一个非官方的开源的API Doc的框架，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。

地址：https://github.com/springfox/springfox

SpringFox 3.0.0 发布（突破性的变更版本），支持OpenApi 3.0.3，有springboot的整合的starter，使用更便捷
基于OpenAPi规范-新版SpringBoot2.x整合Swagger3.x 。

3.2 SpringBoot添加pom文件依赖

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

3.3 swagger的配置类

import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.actuate.autoconfigure.endpoint.web.CorsEndpointProperties;
import org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties;
import org.springframework.boot.actuate.autoconfigure.web.server.ManagementPortType;
import org.springframework.boot.actuate.endpoint.ExposableEndpoint;
import org.springframework.boot.actuate.endpoint.web.*;
import org.springframework.boot.actuate.endpoint.web.annotation.ControllerEndpointsSupplier;
import org.springframework.boot.actuate.endpoint.web.annotation.ServletEndpointsSupplier;
import org.springframework.boot.actuate.endpoint.web.servlet.WebMvcEndpointHandlerMapping;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

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

/**
 *<a href="http://localhost:8081/swagger-ui/index.html#/"> swagger访问地址</a>
 */
@Component
@Data
@ConfigurationProperties("swagger")  //配置swagger.enable的前缀
@EnableOpenApi
public class SwaggerConfiguration {
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
     */
    private Boolean enable;
    /**
     * 项目应用名
     */
    private String applicationName = "access-control";
    /**
     * 项目版本信息
     */
    private String applicationVersion = "1.0";
    /**
     * 项目描述信息
     */
    private String applicationDescription = "智能门禁系统:API接口文档";
    //第一个 Docket，每一个Docket描述一组文档
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(new ApiInfoBuilder()
                        .title(applicationName)
                        .description(applicationDescription)
                        .version(applicationVersion)
                        .build())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }
    /**
     * 增加如下配置可解决Spring Boot 6.x 与Swagger 3.0.0 不兼容问题
     **/
    @Bean
    public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier,
                                                                         ServletEndpointsSupplier servletEndpointsSupplier,
                                                                         ControllerEndpointsSupplier controllerEndpointsSupplier,
                                                                         EndpointMediaTypes endpointMediaTypes,
                                                                         CorsEndpointProperties corsProperties,
                                                                         WebEndpointProperties webEndpointProperties,
                                                                         Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList<>();
        Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
        return new WebMvcEndpointHandlerMapping(endpointMapping,
                webEndpoints, endpointMediaTypes,
                corsProperties.toCorsConfiguration(),
                new EndpointLinksResolver(allEndpoints, basePath),
                shouldRegisterLinksMapping, null);
    }
    private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
        return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath)
                || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
    }
}

此配置类中有一个方法：webEndpointServletHandlerMapping，也就是我在第二部分提到的解决NPE问题的方法，同时需要在application.properties中增加配置：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

如果删除了webEndpointServletHandlerMapping方法和spring.mvc.pathmatch.matching-strategy=ant_path_matcher 配置的话就会出现这个bug：

配置类中有个enable的属性，这个值也是在application.properties定义的

swagger.enable=true

用来控制swagger是否可用的。

3.4 使用

3.4.1 controller上使用

3.4.2 请求参数类上使用

基本上我画红框的这四个注解就足够用了，当然还有一些其他的注解，感兴趣的可以自己搜一下，也可以先参考这篇文档

3.5 页面访问

我的springboot的端口是8081，启动服务之后，访问：http://localhost:8081/swagger-ui/index.html

由于我这个只写了POST，如果还有其他的请求方式就是不同的颜色了。

3.6 使用方法

在每一个请求下面都一个Try it out，如果没有请求参数直接访问，有参数就输入参数，就可以直接访问本地进行自测了。当然部署到test环境的话就是对应的IP地址端口或域名在拼接/swagger-ui/index.html就可以访问了，生产环境是不可以访问的，这个时候就是把swagger.enable的值改为false就可以了。

-----------你知道的越多，不知道的越多---------