springboot之swagger快速啟動

  • 2019 年 10 月 3 日
  • 筆記

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,讓我們自己的配置也具有提示的功能，具體介紹請產考：配置提示 配置提示 配置提示 配置提示 配置提示 …
image.png

image.png

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.purge.swagger</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是否正常。

image.png

總結

簡單的starter程式碼編寫可以減少新模組的複雜性，只需要簡單的配置就可以使用相應的特性，減少複製程式碼不必要的錯誤。

示例程式碼地址: swagger-spring-boot

VirMach 便宜 VPS

QNews

QNews