简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

Spring Boot 整合 Swagger

引入依赖

<!--整合swagger-->
<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>
<!--UI增强-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

配置 Swagger Ui 主界面基本信息

swagger 配置信息也可以不用配置在 yml 文件中， 可以在配置文件中直接定义。

server:
  port: 8763
swagger:
  addr: localhost
  port: ${server.port}
  profiles:
    title: 标题
    description: 描述
    version: 1.0
    termsOfServiceUrl: termsOfServiceUrl
    license: license
    licenseUrl: http://${swagger.addr}:${swagger.port}/doc.html
  contact:
    name: swagger2
    email: xxxxxxxx@163.com
    url: http://${swagger.addr}:${swagger.port}/swagger-ui.html}

增加 Swagger 配置类

定义 Swagger 属性配置类，读取 yml 配置中的信息， 同时设置默认值，yml 中配置不存在时取默认值。

@Data
@Component
public class SwaggerProperties {

    @Value("${swagger.profiles.title:默认标题}")
    private String title;
    @Value("${swagger.profiles.description:默认描述}")
    private String description;
    @Value("${swagger.profiles.version:1.0}")
    private String version;
    @Value("${swagger.profiles.termsOfServiceUrl:}")
    private String termsOfServiceUrl;
    @Value("${swagger.profiles.license:}")
    private String license;
    @Value("${swagger.profiles.licenseUrl:}")
    private String licenseUrl;
    @Value("${swagger.port:${server.port}}")
    private String port;
    @Value("${swagger.addr:localhost}")
    private String addr;
    @Value("${swagger.contact.name:}")
    private String contactName;
    @Value("${swagger.contact.email:}")
    private String contactEmail;
    @Value("${swagger.contact.url:}")
    private String contactUrl;
    
}

配置SwaggerApi， 在配置类中添加以下注解 @Configuration ： 标注这是一个配置类 @EnableSwagger2 : 开启Swagger 文档 @EnableSwaggerBootstrapUI： 开启 Swagger UI 增强

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

    @Autowired
    private SwaggerProperties properties;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于生成API信息
                .apiInfo(apiInfo())
                //select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .select()
                //用于指定扫描哪个包下的接口
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                //选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .paths(PathSelectors.any())
                .build();
    }

    /*
     *用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //用来自定义API的标题
                .title(properties.getTitle())
                //用来描述整体的API
                .description(properties.getDescription())
                //可以用来定义版本
                .version(properties.getVersion())
                //用于定义服务的域名
                .termsOfServiceUrl(properties.getTermsOfServiceUrl())
                .license(properties.getLicense())
                .licenseUrl(properties.getLicenseUrl())
                //创建人信息
                .contact(new Contact(
                        properties.getContactName(),
                        String.format(properties.getContactUrl()),
                        properties.getContactEmail()
                ))
                .build();
    }
}

访问 Swagger 文档

默认访问地址: http://localhost:port/swagger-ui.html

UI增强后访问地址: http://localhost:port/doc.html

常用注解

• @ApiIgnore 忽略添加了该注解的方法或类，使其不在文档页面进行展示。

  作用在控制器类 忽略被该注解标注的控制器的所有方法，使其不在文档页面进行展示。

  作用在属性 忽略被该注解标注的属性，使其不在文档页面进行展示。

  作用在方法 忽略被该注解标注的方法， 使其不展示在文档界面， 例如：

@Api(tags = "swagger 控制器1")
@RestController
@RequestMapping("swagger")
public class SwaggerController {

    @PostMapping("testSwagger1")
    @ApiOperation(value = "Swagger 测试接口1", httpMethod = "POST", notes = "Swagger测试接口1")
    public void test1(){
    }

    @ApiIgnore
    @PostMapping("testSwagger2")
    @ApiOperation(value = "Swagger 测试接口2", httpMethod = "POST", notes = "Swagger测试接口2")
    public void test2(){
    }
}

如下所示，【Swagger测试接口2】 由于被@ApiIgnore 标注，故而不展示在文档页，文档中只能看到 【Swagger测试接口1】

• @Api
  用在类上，该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性

  • tags：API分组标签。具有相同标签的API将会被归并在一组内展示。

  • value：如果tags没有定义，value将作为Api的tags使用

  • description：API的详细描述 usage:
    @Api(tags = "swagger 控制器1" , description = "这是swagger控制器")

• @ApiOperation 在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

  • value: 对操作的简单说明，长度为120个字母，60个汉字。
  • notes: 对操作的详细说明。
  • httpMethod: HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" , "PATCH"。
  • code: 默认为200，有效值必须符合标准的HTTP Status Code Definitions。

  usage: @ApiOperation(value = "Swagger 测试接口1", httpMethod = "POST", notes = "Swagger测试接口1")

• @ApiParam 增加对参数的元信息说明。可与@ApiModel配合使用。其主要的属性有

  • required: 是否必传，默认为false
  • value: 参数说明

• @ApiModel 描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候） 提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有：

  • value: model的别名，默认为类名
  • description: model的详细描述

• @ApiModelProperty 描述一个model的属性, 对model属性的注解，主要的属性值有：

  • value: 属性描述

  • example: 属性的示例值

  • required: 是否为必须值

使用示例：

@Data
@ApiModel(value = "测试实体", description = "测试实体描述")
public class TestDto {

    @ApiModelProperty(name = "名字", required = false, example = "张三")
    private String name;

    @ApiModelProperty(name = "编码", required = false, example = "001")
    private String code;
    
}

• @ApiImplicitParams 用在方法上，注解ApiImplicitParam的容器类，以数组方式存储。

• @ApiImplicitParam 对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定，但这个@ApiImplicitParam注解可以以统一的方式定义参数列表，也是在Servelet及非JAX-RS环境下，唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下参数属性：

  • name: 参数名称
  • value: 参数描述
  • required: 是否必传
  • dataType: 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
  • paramType: 参数的传入（请求）类型，可选的值有path, query, body, header , form。

  usage:

  @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "唯一标识符", required = true, paramType = "form", dataType = "String"),
  })
  

• @ApiResponses 注解@ApiResponse的包装类，数组结构。即使需要使用一个@ApiResponse注解，也需要将 @ApiResponse注解包含在注解@ApiResponses内。

• @ApiResponse 描述一个操作可能的返回结果。当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。但Swagger不支持同一返回码，多种返回类型的注解。注意：这个注解必须被包含在@ApiResponses注解中。

  • code: HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
  • message: 更加易于理解的文本消息
  • response: 返回类型信息，必须使用完全限定类名，比如“com.xyz.cc.Person.class”。
  • responseContainer: 如果返回类型为容器类型，可以设置相应的值。有效值为 "List", "Set" ，"Map"，其他任何无效的值都会被忽略。

注解使用案例

1、@ApiImplicitParams 和 @ApiResponse 一般是配合 @GetMapping 使用。

2、同一接口有多种返回格式时，可以使用 @ApiResponses 和 @ApiResponse 使用不同的返回码返回不同的结果，如下 ”Swagger 测试GET接口“ 所示。

3、@ApiParam 和 @ApiModel 可以搭配使用， 如下 ”Swagger 测试POST接口“所示。

@Api(tags = "swagger 控制器2", description = "这是swagger控制器2")
@RestController
@RequestMapping("swagger2")
public class SwaggerController2 {

    @GetMapping("testGet")
    @ApiOperation(value = "Swagger 测试GET接口", httpMethod = "GET", notes = "Swagger测试GET接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "id", required = false, paramType = "form", dataType = "String"),
            @ApiImplicitParam(name = "name", value = "名称", required = false, paramType = "form", dataType = "String"),
    })
    @ApiResponses({
            @ApiResponse(code = 200,message = "响应1",response = TestDto.class),
            @ApiResponse(code = 201,message = "响应2",response = Test2Dto.class),
    })
    public CommonResult testGet(@RequestParam(name = "id", required = false, defaultValue = "1") String id
            , @RequestParam(name = "name", required = false, defaultValue = "1") Integer name) {
        return new CommonResult(new TestDto());
    }

    @PostMapping("testPost")
    @ApiOperation(value = "Swagger 测试POST接口", httpMethod = "GET", notes = "Swagger测试POST接口")
    public CommonResult<TestDto> testPost(@ApiParam @RequestBody TestDto params){
        return new CommonResult<>(new TestDto());
    }

}

Swagger 分组

Swagger 分组通过 Docket.groupName() 方法来区分实现

方式一：静态配置

通过在配置类中注入多个bean来实现， 不同的bean 扫描不同包下的方法。

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

    @Autowired
    private SwaggerProperties properties;

    /*
     *用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //用来自定义API的标题
                .title(properties.getTitle())
                //用来描述整体的API
                .description(properties.getDescription())
                //可以用来定义版本
                .version(properties.getVersion())
                //用于定义服务的域名
                .termsOfServiceUrl(properties.getTermsOfServiceUrl())
                .license(properties.getLicense())
                .licenseUrl(properties.getLicenseUrl())
                //创建人信息
                .contact(new Contact(
                        properties.getContactName(),
                        String.format(properties.getContactUrl()),
                        properties.getContactEmail()
                ))
                .build();
    }

    @Bean("defaultApi")
    public Docket defaultApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于生成API信息
                .apiInfo(apiInfo())
                //配置不同的分组
                .groupName("defaultGroup")
                //select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .select()
                //用于指定扫描哪个包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                //选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .paths(PathSelectors.any())
                .build();
    }

    @Bean("testApi")
    public Docket testApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于生成API信息
                .apiInfo(apiInfo())
                //配置不同的分组
                .groupName("testGroup")
                //select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .select()
                //用于指定扫描哪个包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                //选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .paths(PathSelectors.any())
                .build();
    }

}

方式二：动态配置

通过自定义注解，来实现接口的动态分组

定义枚举类，配置分组的文档显示分组名以及bean实例id

/**
 * Swagger接口文档分组枚举
 */
@Getter
@AllArgsConstructor
public enum ApiGroupEnum {

    DEFAULT("default", "Default", "defaultDocket"),

    TEST("test", "测试接口", "testDocket"),

    ;

    public String groupKey;

    public String groupName;

    //unique
    public String beanName;
    
}

自定义注解，通过在控制器中添加该注解，实现 API 的动态分组

/**
 * Swagger接口文档分组注解
 * <pre>
 * 在Controller类上添加该注解，在注解中指定所属分组。
 * </pre>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ApiGroup {

	ApiGroupEnum[] group() default ApiGroupEnum.DEFAULT;

}

Swagger 配置辅助类，包含一系列配置 Swagger 的方法， 包括动态配置分组的方法。

/**
 * Swagger配置辅助方法基础类
 */
public abstract class SwaggerConfigHelper {

    @Autowired
    private SwaggerProperties properties;

	@Autowired
    ApplicationContext applicationContext;

    /**
     * 根据枚举类创建Docket, ApiGroupEnum
     *
     * @param applicationContext
     * @return
     */
    public void buildDocket(ApplicationContext applicationContext) {
        DefaultListableBeanFactory beanFactory = (DefaultListableBeanFactory) applicationContext.getAutowireCapableBeanFactory();
        for (ApiGroupEnum apiGroupEnum : ApiGroupEnum.values()) {
            beanFactory.registerSingleton(apiGroupEnum.getBeanName(), buildProductApi(apiGroupEnum.getGroupName(), apiGroupEnum.getGroupKey()));
        }
    }

    /**
     * 根据分组构建完整的API注册信息
     *
     * @param apiGroupName
     * @param apiGroupKey
     * @return
     */
    public Docket buildProductApi(String apiGroupName, String apiGroupKey) {
        Docket docket = buildDocket(apiGroupName)
                .apiInfo(buildBaseProductApiInfo());
        ApiSelectorBuilder builder = buildApiForGroupKey(docket, apiGroupKey);
        return buildApiSecurityAuth(builder);
    }

    /*
     *根据分组名创建Docket
     */
    public Docket buildDocket(String apiGroupName) {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(apiGroupName)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false);
    }

    /*
     *用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     */
    protected ApiInfo buildBaseProductApiInfo() {
        Contact contact = new Contact(properties.getContactName(), properties.getContactUrl(), properties.getContactEmail());
        return buildApiInfo(properties.getTitle(), properties.getDescription(), properties.getVersion(), properties.getTermsOfServiceUrl(), contact);
    }

    @SuppressWarnings("rawtypes")
    protected ApiInfo buildApiInfo(String title, String description, String version, String url, Contact contact) {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version(version)
                .termsOfServiceUrl(url)
                .contact(contact)
                .license(properties.getLicense())
                .licenseUrl(properties.getLicenseUrl())
                .extensions(new ArrayList<VendorExtension>())
                .build();
    }

    /*
     * 根据分组key对API进行注册
     */
    public ApiSelectorBuilder buildApiForGroupKey(Docket docket, String apiGroupKey) {
        return docket.select()
                .apis(getPredicateWithGroup(apiGroupKey))
                .paths(PathSelectors.any());
    }

    /*
     * 通过接口分组过滤
     */
    protected Predicate<RequestHandler> getPredicateWithGroup(String group) {
        return new Predicate<RequestHandler>() {
            @Override
            public boolean apply(RequestHandler input) {
                // 找到controller类上的ApiGroup注解
                Optional<ApiGroup> apiGroup = input.findControllerAnnotation(ApiGroup.class);
                if (apiGroup.isPresent() && Arrays.asList(apiGroup.get().group()).contains(ApiGroupEnum.valueOf(group.toUpperCase()))) {
                    return true;
                }
                return false;
            }
        };
    }

    /*
     * 构建API安全认证
     */
    public Docket buildApiSecurityAuth(ApiSelectorBuilder builder) {
        return builder.build().securityContexts(Lists.newArrayList(buildSecurityContext()))
                .securitySchemes(Lists.newArrayList(apiSecurityKey()));
    }

    private SecurityContext buildSecurityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("/.*"))
                .build();
    }

    /*
     * 默认的认证方式
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Lists.newArrayList(new SecurityReference("BearerToken", authorizationScopes));
    }

    private ApiKey apiSecurityKey() {
        return new ApiKey("BearerToken", "Authorization", "header");
    }

    /*
     * 根据包名对API进行注册
     */
    public ApiSelectorBuilder buildApiForPackage(Docket docket, String basePackage) {
        return docket.select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any());
    }

}

编写配置类， 根据枚举类创建 API 分组。

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig1 extends SwaggerConfigHelper{

    @PostConstruct
    public void buildDocket() {
        buildDocket(applicationContext);
    }

}

分组查询

访问 /swagger-resources ， 查看分组信息，如访问 http://localhost:8763/swagger-resources 接口返回

[{
	"name": "defaultGroup",
	"url": "/v2/api-docs?group=defaultGroup",
	"swaggerVersion": "2.0",
	"location": "/v2/api-docs?group=defaultGroup"
}, {
	"name": "testGroup",
	"url": "/v2/api-docs?group=testGroup",
	"swaggerVersion": "2.0",
	"location": "/v2/api-docs?group=testGroup"
}]

注解使用及页面效果

在控制器添加自定义注解@ApiGroup， group 属性可以填写多个，也可以不填，如果不填归入默认分组。

@ApiGroup(group = {ApiGroupEnum.DEFAULT, ApiGroupEnum.TEST})
@Api(tags = "swagger 控制器2", description = "这是swagger控制器2")
@RestController
@RequestMapping("swagger2")
public class SwaggerController2 {

    @GetMapping("testGet")
    @ApiOperation(value = "Swagger 测试GET接口", httpMethod = "GET", notes = "Swagger测试GET接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "id", required = false, paramType = "form", dataType = "String"),
            @ApiImplicitParam(name = "name", value = "名称", required = false, paramType = "form", dataType = "String"),
    })
    @ApiResponses({
            @ApiResponse(code = 200,message = "响应1",response = TestDto.class),
            @ApiResponse(code = 201,message = "响应2",response = Test2Dto.class),
    })
    public CommonResult testGet(@RequestParam(name = "id", required = false, defaultValue = "1") String id
            , @RequestParam(name = "name", required = false, defaultValue = "1") Integer name) {
        return new CommonResult(new TestDto());
    }

    @PostMapping("testPost")
    @ApiOperation(value = "Swagger 测试POST接口", httpMethod = "GET", notes = "Swagger测试POST接口")
    public CommonResult<TestDto> testPost(@ApiParam @RequestBody TestDto params){
        return new CommonResult<>(new TestDto());
    }

}

效果展示 @ApiGroup(group = {ApiGroupEnum.DEFAULT, ApiGroupEnum.TEST})， group 属性配置了两个分组， 所以页面切换任意一个分组都可以看到 "swagger 控制器2"

Swagger 安全

为了文档安全性考虑，可以添加用户认证， 添加后 Swagger 文档需要输入用户认证信息才能访问。还可以通过@Profile注解限制访问环境。

添加用户认证配置

swagger:
  production: false
  basic:
    enable: true
    username: user
    password: 123456

重新启动，访问文档地址会跳出用户认证界面如下所示

通过@Profile注解控制访问环境

添加配置

spring:
  profiles:
    active: dev

控制器添加注解， 声明开发环境可访问。@Profile注解可声明多个环境，以逗号分隔。如： @Profile({"dev", "prod"})

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Profile({"dev"})
public class SwaggerConfig1 extends SwaggerConfigHelper{

    @PostConstruct
    public void buildDocket() {
        buildDocket(applicationContext);
    }

}

可能存在的问题

1、Failed to start bean 'documentationPluginsBootstrapper'

高版本Spring Boot 整合 Swagger 时可能报错 Failed to start bean 'documentationPluginsBootstrapper' ， 报错信息如下：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

方案一 ： 增加配置属性

Springfox使用的路径匹配是基于AntPathMatcher的, 而Spring Boot 2.6.X使用的是PathPatternMatcher， 所以我们需要添加AntPathMatcher配置。

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

方案二： 增加配置类

添加 WebMvcConfig 配置类， 继承 WebMvcConfigurationSupport 类， 重写 addResourceHandlers（）方法。

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

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html", "doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}