多應用下Swagger的二方庫定製使用

微服務下，一個項目一般會有不少微服務，每一個須要提供Api接口文檔可能會用到Swagger，爲方便使用須要引入以通用的Swagger公共模塊，更好的來匹配當前項目對外展現的Api文檔。

一、依賴

<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>

二、定義一個配置類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;
}

三、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

四、加入啓動類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();
}

}

五、自動化裝配

resources下建立META-INF文件夾，建立文件spring.factories，內容以下：

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

六、微服務端項目加入依賴

<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，生產環境建議不用配置