在面试中深入探讨Swagger的重要性和实际应用的全面指南

前言

最近，一个朋友给我分享了他在国企面试的经历，面试官竟然花了超过半个小时讨论Swagger的问题。虽然面试中遇到各种奇怪的问题是常态，但这次的情况让我觉得这位面试官可能有些犹豫，不知该如何结束这场面试，哈哈！

Swagger简介

Swagger是当前较为流行的RESTful风格API文档工具，开发者在项目中几乎都会使用它。

它提供了一整套工具和规范，使开发人员能够更轻松地创建和维护可读性良好且易于使用的API文档（官方说明）。

title: Swagger  
desc: Swagger 官方网站  
logo: https://static1.smartbear.co/swagger/media/assets/images/swagger_logo.svg  
link: https://swagger.io/  

为什么选择Swagger？

在Swagger出现之前，开发人员需要手动编写和维护API文档，而随着API频繁变更，这使得文档更新变得困难，这对依赖该文档的开发者造成了困扰。

Swagger具有以下几个显著特点：

• 可以根据代码注解自动生成API文档，确保文档的准确性，避免手动维护的麻烦。同时，API文档与API定义能够实时同步更新。
• 提供一个可执行的Web界面，支持在线测试API，用户可以直接在界面上设置参数进行测试，无需额外的工具或插件。
• 支持多种编程语言，如Java、PHP、Python等，开发者可以根据自己的喜好选择语言构建API。

总而言之，Swagger使我们能够将更多时间投入到编码中，而不是在文档维护上耗费精力。因此，实践出真知，先动手跑个demo试试吧。

Swagger搭建步骤

Maven依赖

当前使用的版本为Swagger 3.0和Spring Boot 2.7.6，Swagger 2.0与3.0的依赖包名称变化较大，需特别注意。

<dependency>  
    <groupId>org.springframework.boot</groupId>  
    <artifactId>spring-boot-starter-web</artifactId>  
    <version>2.7.6</version>  
</dependency>  

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

配置类

首先，创建一个控制器TestController类，内含一个简单的请求 /test。

@RestController  
public class TestController {  
    @RequestMapping("/test")  
    public String test(String name) {  
        return name;  
    }  
}  

接下来，创建配置类SwaggerConfig，需要添加@EnableSwagger2注解，这样就搭建好了最基本的Swagger文档环境。

import org.springframework.context.annotation.Configuration;  
import springfox.documentation.swagger2.annotations.EnableSwagger2;  
  
@Configuration  
@EnableSwagger2  
public class SwaggerConfig {  
}  

启动时可能遇到的错误

启动过程中，可能出现如下错误，这通常是由于高版本Spring Boot与Swagger路径匹配策略冲突导致的。

Springfox使用的路径匹配规则为AntPathMatcher，而SpringBoot2.7.6采用的是PathPatternMatcher，两者间出现了冲突。

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

解决方案

针对此错误，有多种解决方案：

1. 降低版本

将Spring Boot版本降低至2.5.X，并将springfox降至3.X以下可以解决问题，但不推荐此做法以保持版本一致性。

2. 统一路径匹配策略

将SpringMVC的路径匹配策略改为ant_path_matcher，在application.yml文件中添加以下配置：

spring:  
  mvc:  
    pathmatch:  
      matching-strategy: ant_path_matcher  

3. 使用@EnableWebMvc注解

在配置类SwaggerConfig上添加@EnableWebMvc注解同样可解决此问题。这是因为Swagger需要通过解析和扫描带有注解的Controller类和方法以生成API文档。

@EnableWebMvc  
@Configuration  
@EnableSwagger2  
public class SwaggerConfig {  
}  

4. 注册BeanPostProcessor

可以在Spring容器中注册一个BeanPostProcessor，定制HandlerMappings以适应Swagger的要求，从而解决可能导致Swagger无法正常工作的路径匹配冲突。

访问Swagger UI

到此问题便已解决，访问Swagger文档路径 http://127.0.0.1:9002/swagger-ui/index.html，你将看到自己编写的API信息及一些Swagger文档的默认配置。

请注意，由于我们在controller方法中使用了@RequestMapping注解而未指定具体的请求方式，因此文档中列出了所有请求方式。为了避免文档冗余，建议明确指定请求方式或使用特定请求方式的@XXXMapping注解。

指定请求方式后效果如下：

API文档配置

浏览器中展示的数据为默认配置，现在我们来定制化文档。

Springfox提供了一个Docket对象，供我们灵活配置Swagger的各项属性。Docket对象内含多个方法配置文档，以下是一些常用配置项。

select

select()返回一个ApiSelectorBuilder对象，是使用apis()、paths()两个方法的前提，用于指定Swagger要扫描的接口和路径。

apis

默认情况下，Swagger会扫描整个项目中的接口，通过apis()方法，可以传入一个RequestHandlerSelector对象实例来指定接口所在的包路径。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .select()  
            .apis(RequestHandlerSelectors.basePackage("com.springboot101.controller"))  
            .build();  
}  

paths

可以仅将特定请求路径的API展示在Swagger文档中，例如路径中包含/test。可以使用apis()和paths()方法一起过滤接口。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .select()  
            .paths(PathSelectors.ant("/test/**"))  
            .build();  
}  

groupName

为生成的Swagger文档指定分组名称，用于区分不同文档组。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .groupName("用户分组")  
            .build();  
}  

要实现文档的多个分组，需要创建多个Docket实例，设置不同的组名，并过滤API条件。

@Bean  
public Docket docket1(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .groupName("商家分组")  
            .select()  
            .paths(PathSelectors.ant("/test1/**"))  
            .build();  
}  

apiInfo

设置API文档的基本信息，如标题、描述、版本等，可以使用ApiInfo对象自定义信息。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .apiInfo(apiInfo()); // 文档基础配置  
}  
  
private ApiInfo apiInfo() {  
    Contact contact = new Contact("小富", "http://fire100.top", "email@example.com");  
    return new ApiInfoBuilder()  
            .title("Swagger学习")  
            .description("程序员小富-带你一起学习 Swagger")  
            .version("v1.0.1")  
            .termsOfServiceUrl("http://fire100.top")  
            .contact(contact)  
            .license("许可证")  
            .licenseUrl("许可链接")  
            .extensions(Arrays.asList(  
                    new StringVendorExtension("我是", "小富"),  
                    new StringVendorExtension("你是", "谁")  
            ))  
            .build();  
}  

enable

可以启用或禁用Swagger文档的生成，某些环境下可能需要在生产中禁用API文档。

@Bean  
public Docket docket(Environment environment) {  
    Profiles of = Profiles.of("dev", "test", "pre");  
    boolean enable = environment.acceptsProfiles(of);  
  
    return new Docket(DocumentationType.SWAGGER_2)  
            .enable(enable)  
            .apiInfo(apiInfo()); // 文档基础配置  
}  

host

设置API文档显示的主机名称或IP地址，即在测试执行接口时使用的IP或域名。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .host("http://test.com") // 请求地址  
            .apiInfo(apiInfo()); // 文档基础配置  
}  

securitySchemes

配置API的安全认证方式，如Bearer、Authorization、Basic等鉴权字段，ApiKey对象中字段含义分别是别名、鉴权字段key、鉴权字段添加的位置。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .securitySchemes(  
                    Arrays.asList(  
                            new ApiKey("Bearer鉴权", "Bearer", "header"),  
                            new ApiKey("Authorization鉴权", "Authorization", "header"),  
                            new ApiKey("Basic鉴权", "Basic", "header")  
                    )  
            );  
}  

配置后，Swagger文档将包含一个Authorize按钮，供用户输入设定的Bearer、Authorization、Basic进行身份验证。

securityContexts

虽然在securitySchemes方法中设置了鉴权字段，但在测试接口时不会自动在header中加入鉴权字段和值，因此需要配置API的安全上下文。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .securitySchemes(  
                    Arrays.asList(  
                            new ApiKey("Bearer鉴权", "Bearer", "header"),  
                            new ApiKey("Authorization鉴权", "Authorization", "header"),  
                            new ApiKey("Basic鉴权", "Basic", "header")  
                    )  
            )  
            .securityContexts(Collections.singletonList(securityContext()));  
}  
  
private SecurityContext securityContext() {  
    return SecurityContext.builder()  
            .securityReferences(  
                    Arrays.asList(  
                            new SecurityReference("Authorization", new AuthorizationScope[0]),  
                            new SecurityReference("Bearer", new AuthorizationScope[0]),  
                            new SecurityReference("Basic", new AuthorizationScope[0])))  
            .build();  
}  

tags

为API文档中的接口添加标签，便于分类和组织。

@Bean  
public Docket docket(Environment environment) {  
    return new Docket(DocumentationType.SWAGGER_2)  
            .tags(new Tag("小富接口", "小富相关的测试接口"))  
}  

授权登录

出于系统安全考虑，通常会为API文档增加登录功能。

引入Maven依赖

Swagger的安全登录基于spring security，需要引入相关Maven依赖。

<dependency>  
    <groupId>org.springframework.boot</groupId>  
    <artifactId>spring-boot-starter-security</artifactId>  
</dependency>  

登录配置

在application.yml文件中配置Swagger的用户名和密码。

spring:  
  security:  
    user:  
      name: admin  
      password: 123456  

再次访问文档时会出现如下登录页：

文档注解

为了在Swagger文档中提供更加详细和完整的内容，我们可以使用其他Swagger内置注解来丰富API文档。

@ApiIgnore

可以使用@ApiIgnore注解来忽略文档中的特定API。

@ApiIgnore  
@GetMapping("/user2/{id}")  
public User test2(@PathVariable Integer id, @RequestBody User user) {  
    return user;  
}  

@ApiModel

使用@ApiModel注解为实体添加描述信息，提升Swagger对Model的描述。

@ApiModel(value = "用户实体类", description = "用于存放用户登录信息")  
@Data  
public class User {  
    @ApiModelProperty(value = "用户名字段", required = true, example = "#公众号：程序员小富")  
    private String name;  
  
    @ApiModelProperty(value = "年龄", required = true, example = "19")  
    private Integer age;  
  
    @ApiModelProperty(value = "邮箱", required = true, example = "#公众号：程序员小富")  
    private String email;  
}  

@Api

用以标记控制器类，并提供接口的详细信息和配置项。

@Api(value = "用户管理接口描述",  
        description = "用户管理接口描述",  
        hidden = false,  
        produces = "application/json",  
        consumes = "application/json",  
        protocols = "https",  
        tags = {"用户管理"},  
        authorizations = {  
                @Authorization(value = "apiKey", scopes = {  
                    @AuthorizationScope(scope = "read:user", description = "读权限"),  
                    @AuthorizationScope(scope = "write:user", description = "写权限")  
                })  
        })  
@RestController  
public class TestController {  
}  

@ApiOperation

该注解用于描述接口方法。

@ApiOperation(  
        value = "获取用户信息",  
        notes = "通过用户ID获取用户的详细信息",  
        hidden = false,  
        response = UserDto.class,  
        tags = {"用户管理"},  
        produces = "application/json",  
        consumes = "application/json",  
        protocols = "https",  
        authorizations = {  
            @Authorization(value = "apiKey", scopes = {@AuthorizationScope(scope = "read:user", description = "读权限")}),  
            @Authorization(value = "Basic")  
        },  
        responseHeaders = {@ResponseHeader(name = "X-Custom-Header", description = "Custom header", response = String.class)},  
        code = 200,  
        httpMethod = "GET"  
)  
@GetMapping("/user1")  
public UserDto user1(@RequestBody User user) {  
    return new UserDto();  
}  

@ApiImplicitParams 和 @ApiImplicitParam

这两个注解可用于对API方法中的参数进行详细说明，确保参数信息的透明度。

@ApiImplicitParams({  
        @ApiImplicitParam(name = "用户名", value = "用户名称信息", required = true, dataType = "String", paramType = "query")  
})  
@GetMapping("/user")  
public String user(String name) {  
    return name;  
}  

总结

尽管在面试中不太可能过多考察Swagger这类工具，但作为开发者，养成良好的文档规范习惯尤为重要。无论使用Swagger还是其他文档工具，编写清晰、详尽的API文档都应成为我们的一项基本素养。

感谢大家的阅读，希望这些内容对你们有所帮助，我们下篇见！

代码示例

https://github.com/chengxy-nds/Springboot-Notebook/tree/master/springboot101/%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3/springboot-swagger