Swagger API文件集中化註冊管理

介面文件是前後端開發對接時很重要的一個元件。手動編寫介面文件既費時，又存在文件不能隨程式碼及時更新的問題，因此產生了像swagger這樣的自動生成介面文件的框架。swagger文件一般是隨專案程式碼生成與更新，訪問地址也是基於專案地址，因此對專案數不多的團隊還好。如果團隊的專案很多，比如採用微服務架構的團隊，動則幾十甚至上百個服務專案，那就意味著前端開發人員需要記住幾十甚至上百個swagger文件地址，那就很不友好了。目前貌似還沒有較流行的API文件集中化管理專案（也或者是我沒找到），因此花了點時間自己整合了一個，介紹如下。

1. swagger-bootstrap-ui專案

該專案是github上的一個開源專案（https://github.com/xiaoymin/swagger-bootstrap-ui ），對swagger ui做了增強，功能整體看起來要豐富一些。來看看效果，

該專案的除錯url地址原本是基於自身服務的，我將它改為了註冊服務的url地址，以支援註冊服務的介面除錯。調整後的原始碼地址： https://github.com/ronwxy/swagger-bootstrap-ui

2. swagger api註冊服務

該專案整合了swagger-bootstrap-ui，並提供了swagger api註冊介面，接受所有提供了有效配置的服務專案註冊，讓註冊的服務在一個頁面上可統一檢視，再也不用記太多文件地址了。

啟動註冊服務後，訪問 http://localhost:11090/doc.html 開啟文件頁面。如上圖，可通過下拉選單來選擇不同專案，載入專案的介面文件檢視或除錯。
專案地址： 關注本文最後二維碼公眾號，回覆“swagger”獲取原始碼地址 （新公眾號，希望多點粉絲交流。如果覺得有用，不要吝嗇你的star，反正又不要錢，O(∩_∩)O）

3. 服務端配置

在業務服務端，需要提供一些配置。
首先，需要配置一些Bean，如下提供了一個配置類（這裡只列出了主要部分，完整程式碼參考： https://github.com/ronwxy/base-spring-boot）

public class Swagger2AutoConfiguration {

    @Bean
    public Docket restApi() {
        ParameterBuilder builder = new ParameterBuilder();
        builder.name("x-auth-token").description("授權token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false);
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(apisBasePackage))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(Collections.singletonList(builder.build()))
                .apiInfo(apiInfo());
    }

    @Profile({"dev"})
    @Bean
    public CommandLineRunner swaggerRegistar(ConfigurableApplicationContext context) {
        return new SwaggerInfoRegistar(context);
    }

    /**
     * use to register swagger api info url to swagger api registry;
     *
     * @author liubo
     */
    public class SwaggerInfoRegistar implements CommandLineRunner {
        @Override
        public void run(String... args) throws Exception {
            String url = buildLocalSwaggerDocsUrl();
            registerLocalSwaggerUrl(url);
        }

        /**
         * register the v2/api-docs url
         *
         * @param url
         */
        private void registerLocalSwaggerUrl(String url) {
            RestTemplate restTemplate = new RestTemplate();
            restTemplate.getMessageConverters().add(new FormHttpMessageConverter());
            MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
            body.add("project", getApiTitle());
            body.add("url", url);
            ResponseEntity<Map> re = restTemplate.postForEntity(getSwaggerRegisterUrl(), body, Map.class);
            if (HttpStatus.OK.equals(re.getStatusCode())) {
                logger.info("swagger api registered success to {}", getSwaggerRegisterUrl());
            } else {
                logger.warn("swagger api registered failed [{}]", re.getBody().get("msg"));
            }
        }
    }

}

該類完成了swagger的基本配置，同時將swagger的/v2/api-docs地址註冊到了步驟2中介紹的註冊服務。 

然後，因為要從註冊服務端呼叫該業務服務的介面進行除錯，存在跨域，因此服務需要做跨域支援，配置檔案中新增如下定義，

@Bean
@ConditionalOnMissingBean(name = "corsFilterRegistrationBean")
public FilterRegistrationBean corsFilterRegistrationBean() {
    UrlBasedCorsConfigurationSource corsConfigurationSource = new UrlBasedCorsConfigurationSource();

    CorsConfiguration corsConfiguration = new CorsConfiguration();
    corsConfiguration.applyPermitDefaultValues();
    corsConfiguration.setAllowedMethods(Arrays.asList(CorsConfiguration.ALL));
    corsConfiguration.addExposedHeader(HttpHeaders.DATE);

    corsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);

    CorsFilter corsFilter = new CorsFilter(corsConfigurationSource);
    FilterRegistrationBean filterRegistrationBean = new FilterRegistrationBean();
    filterRegistrationBean.setFilter(corsFilter);
    filterRegistrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE);
    filterRegistrationBean.addUrlPatterns("/*");

    return filterRegistrationBean;
}

 

最後，在屬性配置檔案application.yml中配置一些必要的屬性，

swagger:
  api-title: Demo標題  #會展示在下拉選單框中，一般寫專案名稱
  api-description:  Demo描述，集中註冊
  group-name: Demo專案
  apis-base-package: cn.jboost.springboot.swagger # API類所在包名
  swagger-registry-path: http://localhost:11090/swagger/register  #就是2中註冊服務的註冊介面地址

 

配置完後， 就可以像一般專案一樣編寫介面類，加swagger註解。專案啟動時， 會自動向註冊服務完成註冊，重新整理註冊服務的文件頁面即可在下拉選單看到。

4. 總結

本文介紹了一個基於swagger ui增強版專案swagger-bootstrap-ui的介面文件集中化管理實現。採用該實現，將所有swagger線上介面文件集中管理，有效提高前後端對接效率。

 

關注本文最後二維碼公眾號（jboost-ksxy），回覆“swagger”獲取原始碼地址 （新公眾號，希望多點粉絲交流，^_^）

 

如果覺得本文有用，歡迎轉發、推薦。

我的個人部落格地址：http://blog.jboost.cn
我的github地址：https://github.com/ronwxy
我的微信公眾號：jboost-ksxy （歡迎關注，及時獲取技術乾貨分享）
———————————————————————————————————————————————————————————————

歡迎關注我的微信公眾號，及時獲取最新分享