SpringBoot2.6.2集成Swagger2.9.2

1 背景

SpringBoot作为微服务首选框架，为其他服务提供大量的接口服务。接口对接方需要实时最近的接口文档。

Swagger可以通过代码和注释自动为web项目生成在线文档，这里使用Swagger。

2 使用

2.1 maven依赖

 
        <dependency>
            
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>
        <dependency>
            
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>

2.2 配置代码

Springfox提供Docket对象，为其设置相关属性，将其注册成为spring的bean后，可以在接口文档中展示（可配置多个Docket的bean，对应不同分组的接口）。

其中@Configuration、@Bean均为spring初始化bean相关的注解。@EnableSwagger2表示启用swagger2。

package com.aac.bpmmanager.config;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.aac.bpmmanager.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("bpm-manager api")
                .description("BPM后台管理系统RESTful API")
                .contact(contact())
                .version("0.0.1")
                .build();
    }

    private Contact contact() {
        return new Contact("Zhang SanFeng", "*****", "Zhang SanFeng@*****.com");
    }
}

2.3 接口配置

通过在控制器和接口方法上加上相关注解，可以给接口和控制器添加相关的接口说明信息。

参数实体类代码：

package com.aac.bpmmanager.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(value = "员工实体类")
public class Employee {

    @ApiModelProperty(value = "域账号")
    private String account;

    @ApiModelProperty(value = "密码，即yyyymmdd格式生日")
    private String password;

    @ApiModelProperty(value = "姓")
    private String familyName;

    @ApiModelProperty(value = "名")
    private String firstName;

    @ApiModelProperty(value = "获取用户全名")
    public String getFullName() {
        return familyName + firstName;
    }

	public String getAccount() {
		return account;
	}

	public void setAccount(String account) {
		this.account = account;
	}

	public String getPassword() {
		return password;
	}

	public void setPassword(String password) {
		this.password = password;
	}

	public String getFamilyName() {
		return familyName;
	}

	public void setFamilyName(String familyName) {
		this.familyName = familyName;
	}

	public String getFirstName() {
		return firstName;
	}

	public void setFirstName(String firstName) {
		this.firstName = firstName;
	}
}

接口代码：

package com.aac.bpmmanager.controller;

import com.aac.bpmmanager.constant.TimeConstants;
import com.aac.bpmmanager.pojo.FormCounter;
import com.aac.bpmmanager.service.FormCounterService;
import com.aac.bpmmanager.util.JDK8DateUtils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("form/counters")
@Api(value = "表单数量统计接口类")
public class FormCountersController {

    @Autowired
    private FormCounterService formCounterService;

    /**
     * 获取统计数据实体类集合
     * @return
     */
    @GetMapping
    @ApiOperation(value = "获取所有表单统计数据", notes = "返回类型为List")
    public List<FormCounter> getFormCounters() {
        return formCounterService.getFormCounters();
    }
}

2.4 配置yml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

在springboot2.6.2中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出错，解决办法是切换回原先的AntPathMatcher。

2.5 访问

启动项目后，通过以下方式访问swagger2的接口说明
http://localhost:8090/swagger-ui.html

2.6 swagger2静态资源

swagger通过webjars的方式，来实现网页方式的接口访问。

如配置拦截器、shiro、spring security等，需对以下页面放行，来保证swagger页面的正常访问：

@Configuration
public class ShiroConfig {

    @Bean
    public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager) {
        ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean();

        shiroFilterFactoryBean.setSecurityManager(securityManager);
        shiroFilterFactoryBean.setLoginUrl("/login.html");
        shiroFilterFactoryBean.setSuccessUrl("/");

        Map<String, String> filterChainDefinitionMap = new LinkedHashMap<>();
        filterChainDefinitionMap.put("/swagger*/**", "anon");
        filterChainDefinitionMap.put("/css/**", "anon");
        filterChainDefinitionMap.put("/js/**", "anon");
        filterChainDefinitionMap.put("/authentication", "anon"); // 认证接口，最好位于根路径下。
        filterChainDefinitionMap.put("/visitor", "anon");
        filterChainDefinitionMap.put("/logout", "logout"); // Shiro自带的注销接口
        filterChainDefinitionMap.put("/**", "user"); // 已经登录后，所有接口都能被当前用户访问。
        shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);

        Map<String, Filter> filterMap = new HashMap<>();
        filterMap.put("logout", logoutFilter());
        shiroFilterFactoryBean.setFilters(filterMap);

        return shiroFilterFactoryBean;
    }
}

参考文章
https://blog.csdn.net/weixin_48678547/article/details/121939552
https://blog.csdn.net/goalietang/article/details/108555689
https://blog.csdn.net/qq_26993175/article/details/108975701