Swagger的集成与使用

Swagger是一个规范和完整的API框架，可用于生成、描述、调用Restful风格的Web服务的接口文档。如果在SpringBoot中使用的话，在项目启动后可以自动生成在线可调用的API文档。

Swagger的集成

  1. 首先在pom.xml中添加springfox官方Swagger依赖；
1
2
3
4
5
6
<!--springfox swagger官方Starter-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>${springfox-swagger.version}</version>
</dependency>
  1. 由于Spring默认的路径匹配策略为PATH_PATTERN_PARSER，而SpringFox假设为ANT_PATH_MATCHER，所以需要修改application.yml配置文件，添加如下配置；
1
2
3
4
spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER
  1. 添加Swagger的Java配置，配置好Api信息和需要生成接口文档的类扫描路径，注意在SpringBoot2.6.x以上版本整合时由于兼容性问题需要配置一个BeanPostProcessor的Bean；
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("mall-tiny")
                .contact(new Contact("macro", null, null))
                .version("1.0")
                .build();
    }

    @Bean
    public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return new BeanPostProcessor() {

            @Override
            public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
                if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
                    customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
                }
                return bean;
            }

            private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
                List<T> copy = mappings.stream()
                        .filter(mapping -> mapping.getPatternParser() == null)
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }

            @SuppressWarnings("unchecked")
            private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
                try {
                    Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                    field.setAccessible(true);
                    return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
                } catch (IllegalArgumentException | IllegalAccessException e) {
                    throw new IllegalStateException(e);
                }
            }
        };
    }
}
  1. 访问API文档信息，访问地址：http://localhost:8088/swagger-ui/

Swagger的使用

Swagger主要是通过注解来标注文档内容的。主要有以下注解：
注解名称 描述 常用属性
@Api 用于类，标识这个类是Swagger的资源 tags：给该类下的接口设置标签
@Tag 可用于类或方法，声明一个标签 name：标签名称 description：标签描述
@ApiIgnore 忽略该类的文档生成 value：添加备注
@ApiOperation 用于方法，用于描述一个HTTP请求方法 value：给方法添加描述
@ApiParam 用于参数，用于描述请求参数 value：参数描述 name：参数名称 defaultValue：参数默认值 required：参数是否必填 allowableValues：参数允许范围 type：参数类型
@ApiImplicitParam 代表一个单个API操作，与@ApiImplicitParams联用 paramType：参数请求类型 dataTypeClass：参数值类型 其他类型同@ApiParam
@ApiImplicitParams 多个@ApiImplicitParam注解的集合 参数为@ApiImplicitParam数组
@ApiModel 用于类，声明一个Swagger的模型 value：模型名称 description：模型描述
@ApiProperty 用于参数，声明Swagger模型的属性或填充数据 value：属性描述 name：属性名称 allowableValues：允许值
@ApiResponse 用于描述一个可能的返回结果 responseCode：返回状态码 message：返回信息
@ApiResponses @ApiResponse的集合 参数为@ApiResponse数组

结合Spring Secutiry使用时的注意事项

若访问需要登录认证的接口，则需在访问接口时添加一个合法的Authorization请求头。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
private List<SecurityScheme> securitySchemes() {
        //设置请求头信息
        List<SecurityScheme> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }
...
private List<SecurityReference> defaultAuth() {
        List<SecurityReference> result = new ArrayList<>();
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        result.add(new SecurityReference("Authorization", authorizationScopes));
        return result;
    }

此外，注意需要在Spring Security中配置好Swagger静态资源的无授权访问，比如首页访问路径/swagger-ui/

使用Postman增强Swagger的功能

Postman与Swagger的功能基本一致，但两者各有优劣，可以配合使用。

Postman在阅读JSON格式的对象时更加美观整洁，但是其在文档展示的能力上相比Swagger偏弱。