springboot之swagger快速啓動

springboot之swagger快速啓動

簡介

介紹

可能你們都有用過swagger,能夠經過ui頁面顯示接口信息，快速和前端進行聯調。

沒有接觸的小夥伴能夠參考官網文章進行了解下demo頁面。

多應用

固然在單個應用你們能夠配置SwaggerConfig類加載下buildDocket,就能夠快速構建好swagger了。

代碼大體以下：

/**
 * Swagger2配置類
 * 在與spring boot集成時，放在與Application.java同級的目錄下。
 * 經過@Configuration註解，讓Spring來加載該類配置。
 * 再經過@EnableSwagger2註解來啓用Swagger2。
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    /**
     * 建立API應用
     * apiInfo() 增長API相關信息
     * 經過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展示，
     * 本例採用指定掃描的包路徑來定義指定要創建API的目錄。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 建立該API的基本信息（這些基本信息會展示在文檔頁面中）
     * 訪問地址：http://項目實際地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("更多請關注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

模塊化-Starter

原因

有開發過微服務的小夥伴應該體會過。當微服務模塊多的狀況下，每一個模塊都須要配置這樣的一個類進行加載swagger。形成每一個模塊都存在大體同樣的SwaggerConfig,極端的狀況下，有些朋友複製其餘模塊的SwaggerConfig進行改造以後，發現仍然加載不出swagger的狀況，形成明明是複製的，爲什麼還加載不出，排查此bug及其費時間。

在此之上，能夠構建出一個swagger-starter模塊，只須要引用一個jar，加載一些特殊的配置，就能夠快速的使用到swagger的部分功能了。

設計

建立模塊swagger-spring-boot-starter。
功能大體以下：

1. 加載SwaggerConfig。
2. 經過配置化配置swagger。
3. Enable加載註解。

1. 建立SwaggerConfig

SwaggerConfig和以前的一致，只是裏面的配置須要外部化。

@Configuration
@PropertySource(value = "classpath:swagger.properties", ignoreResourceNotFound = true, encoding = "UTF-8")
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerConfig {

  @Resource
  private SwaggerProperties swaggerProperties;

  @Bean
  public Docket buildDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(buildApiInf())
        .select()
        .apis(RequestHandlerSelectors.basePackage(""))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo buildApiInf() {
    return new ApiInfoBuilder()
        .title(swaggerProperties.getTitle())
        .description(swaggerProperties.getDescription())
        .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
        .contact(new Contact("skyworth", swaggerProperties.getTermsOfServiceUrl(), ""))
        .version(swaggerProperties.getVersion())
        .build();
  }
}

2. 建立SwaggerProperties 配置相關

配置經過@PropertySource註解加載resources目錄下的swagger.properties。

建立SwaggerProperties配置類,這個類裏包含了通常swagger初始化要使用的一些經常使用的屬性，如掃描包路徑、title等等。

@Data
@ToString
@ConfigurationProperties(SwaggerProperties.PREFIX)
public class SwaggerProperties {

  public static final String PREFIX = "swagger";

  /**
   * 文檔掃描包路徑
   */
  private String basePackage = "";

  /**
   * title 如: 用戶模塊系統接口詳情
   */
  private String title = "深蘭雲平臺系統接口詳情";

  /**
   * 服務文件介紹
   */
  private String description = "在線文檔";

  /**
   * 服務條款網址
   */
  private String termsOfServiceUrl = "https://www.deepblueai.com/";

  /**
   * 版本
   */
  private String version = "V1.0";


}

作好這兩件事情基本大工搞成了，爲了更好的使用配置，在idea裏和官方starter包同樣，咱們還須要配置一個additional-spring-configuration-metadata.json,讓咱們本身的配置也具備提示的功能，具體介紹請產考：配置提示 配置提示 配置提示 配置提示 配置提示 ...

3. 加載SwaggerConfig等特性

由於是starter模塊，可能他人的項目目錄和starter模塊的目錄不一致，致使加載不到SwaggerConfig類，咱們須要使用spring.factories把SwaggerConfig類裝載到spring容器。

resources/META-INF

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  io.purge.swagger.SwaggerConfig

固然本次基於Enable方式去加載SwaggerConfig。

建立@EnableSwaggerPlugins註解類，使用@Import(SwaggerConfig.class)將SwaggerConfig導入大工搞成。

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Import(SwaggerConfig.class)
@EnableSwagger2
public @interface EnableSwaggerPlugins {

}

使用

添加依賴

把本身編寫好的swagger經過maven打包，本身項目引用。

<dependency>
  <groupId>com.purgeteam</groupId>
  <artifactId>swagger-spring-boot-starter<factId>
  <version>0.1.0.RELEASE</version>
</dependency>

配置swagger.properties文件

• 在本身項目模塊的resources目錄下 建立swagger.properties配置
• swagger.properties 大體配置以下

swagger.basePackage="swagger掃描項目包路徑"
swagger.title="swagger網頁顯示標題"
swagger.description="swagger網頁顯示介紹"

啓動類添加 @EnableSwaggerPlugins註解。

@EnableSwaggerPlugins
@SpringBootApplication
public class FrontDemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(FrontDemoApplication.class, args);
  }

}

訪問http://ip:端口/swagger-ui.html檢查swagger-ui是否正常。

總結

簡單的starter代碼編寫能夠減小新模塊的複雜性，只須要簡單的配置就可使用相應的特性，減小複製代碼沒必要要的錯誤。

示例代碼地址: swagger-spring-boot