多应用下Swagger的二方库定制使用

Posted 2021-09-14 踮脚被吹跑

微服务下，一个项目通常会有很多微服务，每个需要提供Api接口文档可能会用到Swagger，为方便使用需要引入以通用的Swagger公共模块，更好的来匹配当前项目对外展示的Api文档。

1、依赖

    <dependencies>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
        </dependency>
    </dependencies>

2、定义一个配置类SwaggerProperties

@Configuration
@Getter
@Setter
@PropertySource(value= {"classpath:swagger.properties"})
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {
    /**
     * 标题
     */
    private String title;

    /**
     * 描述
     */
    private String description;

    /**
     * 版本号
     */
    private String version;

    /**
     * api包路径
     */
    private String basePackage;

    /**
     * 联系人
     */
    private String contactName;
}

3、resources文件夹添加配置文件swagger.properties

swagger.version = 1.0
swagger.title = ${spring.application.name} service API Doc
swagger.description = API Doc for ${spring.application.name} service.
swagger.base-package = com.project 
swagger.contact-name = Asan

4、加入启动类SwaggerAutoConfiguration

@Configuration
@EnableOpenApi
@ConditionalOnClass({Docket.class, ApiInfoBuilder.class})
@ConditionalOnProperty(prefix = "swagger", value = "enable")
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerAutoConfiguration {

@Bean
@ConditionalOnMissingBean
public SwaggerProperties swaggerProperties() {
    return new SwaggerProperties();
}

@Bean
public Docket createRestApi(){
    SwaggerProperties properties = swaggerProperties();
    return new Docket(DocumentationType.SWAGGER_2)
            // 生产环境可关闭 Swagger
            .apiInfo(apiInfo(properties))
            .select()
            // api扫描目录
            .apis(RequestHandlerSelectors.basePackage(properties.getBasePackage()))
            .paths(PathSelectors.any())
            .build();
}

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

}

5、自动化装配

resources下创建META-INF文件夹，创建文件spring.factories，内容如下：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\\
com.asan.common.swagger.config.SwaggerAutoConfiguration

6、微服务端项目加入依赖

 <dependency>
     <groupId>com.asan</groupId>
     <artifactId>common-swagger</artifactId>
 </dependency>       

如果需要自定义Api文档名称，则可以自行在对应yaml配置文件中修改

# Swagger 配置项
swagger:
  enable: true
  title: 自定义的标题
  description: 自定义的描述
  version: 1.0
  base-package: com.asan.controller
  contact-name: 阿三

swagger.enable=true 开启swagger，生产环境建议不用配置