基于 springfox-boot-starter 二次封装接口文档 starter 组件

随着微服务架构的普及，API 文档的重要性日益凸显。Swagger 作为一款强大的 API 文档工具，可以帮助开发者快速生成和维护 API 文档。本文将介绍如何通过 Spring Boot 封装 Swagger，使其更加灵活和易用。

1. 为什么需要封装 Swagger？

虽然 Swagger 提供了丰富的功能，但在实际项目中，我们往往需要对 Swagger 进行一些定制化配置，以满足特定的需求。例如： 统一 API 文档的基本信息（如标题、描述、版本等）。 动态配置 API 的扫描路径和包名。 集成安全认证，保护 API 接口的安全性。 通过封装 Swagger，我们可以将这些配置集中管理，使项目更加简洁和易于维护。

2. 封装 Swagger 的步骤

2.1 创建配置属性类

首先，我们需要创建一个配置属性类 SwaggerProperties，用于读取外部配置文件中的 Swagger 相关配置。

@ConfigurationProperties(prefix = "kit.swagger")
@Data
public class SwaggerProperties {

    private String title;

    private String description;

    private String version;

    private String basePackage;

    private String prefixPath;

    private String contactName;

    private String contactUrl;

    private String contactEmail;

}

2.2 创建 Swagger 自动配置类

接下来，创建一个自动配置类 SwaggerAutoConfig，用于初始化 Swagger 并应用配置属性。

@Configuration
@EnableConfigurationProperties(SwaggerProperties.class)
@EnableOpenApi
public class SwaggerAutoConfig {

    private final SwaggerProperties properties;

    public SwaggerAutoConfig(SwaggerProperties properties) {
        this.properties = properties;
    }

    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")
                .enable(true)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(properties.getBasePackage()))
                .paths(PathSelectors.ant(properties.getPrefixPath()))
                .build()
                .securitySchemes(List.of(apiKey()))
                .securityContexts(List.of(securityContext()));

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(properties.getTitle())
                .description(properties.getDescription())
                .version(properties.getVersion())
                .contact(new Contact(properties.getContactName(), properties.getContactUrl(), properties.getContactEmail()))
                .build();
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(auth())
                .forPaths(PathSelectors.any())
                .build();
    }

    private List<SecurityReference> auth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "global");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return List.of(new SecurityReference("Authorization", authorizationScopes));
    }

    private SecurityScheme apiKey() {
        return new ApiKey("Authorization", "Authorization", "header");
    }


}

2.3 自动配置

为了使我们的 Starter 能够自动配置，需要在 META-INF 目录下创建 spring.factories 文件，指定自动配置类。

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.ssn.kit.swagger.SwaggerAutoConfig

3. 测试

引入自定义 starter 组件

        <dependency>
            <groupId>com.ssn.kit</groupId>
            <artifactId>corp-kit-swagger</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>

编写 controller

@RestController
@RequestMapping("test")
@Api(tags = {"测试"})
public class TestController {

    @GetMapping("")
    @ApiOperation(value = "获取详情")
    public String test() {
        return "test";
    }
}

application.yml 进行相关配置

kit:
  swagger:
    base-package: com.ssn.kit.swagger
    title: 测试服务
    description: 测试服务
    contact-email: ""
    contact-name: ""
    contact-url: ""
    prefix-path: "/**"
    version: "1.0.0"

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

启动程序访问 http://localhost:8080/swagger-ui/index.html 即可看到接口详情，同时也可以直接测试接口功能

总结

通过封装 Swagger，我们可以更好地管理和维护 API 文档，提升开发效率和文档质量