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 （歡迎關注，及時獲取技術乾貨分享）
———————————————————————————————————————————————————————————————

歡迎關注個人微信公衆號，及時獲取最新分享

 

原文出處：https://www.cnblogs.com/spec-dog/p/11104472.html