闊歩APIドキュメントを闊歩APIドキュメントの集中レジストリ

闊歩APIドキュメントの集中レジストリ

 

インターフェイスのドキュメントは、ドッキングアセンブリの開発が終了する前と後に非常に重要です。書き込みインタフェースドキュメントマニュアル時間がかかり、インタフェースドキュメントよう闊歩の自動生成のためのフレームワークを生成するように、更新することができないコード文書に問題があります。一般的に、プロジェクトのコード生成および更新アクセスアドレスと闊歩文書はまた、プロジェクトのアドレスに基づいて、そのプロジェクトチームの数が少ない方が良いです。チームは、このようなマイクロサービスアーキテクチャチームとしてプロジェクト、数十または奉仕プロジェクトの数百もの移動の多くは、それがフロントエンドの開発者が数十または闊歩の文書アドレスの数百を覚えておく必要があることを意味している場合、それは非常に友好的ですA。現在、一見何より人気のAPIドキュメントの集中管理プロジェクト（も、あるいは私が見つかりませんでした）ので、私自身は、以下で説明する、統合いくつかの時間を費やしました。

1.闊歩-ブートストラップ-UIプロジェクト

プロジェクトは、（GitHubの上のオープンソースプロジェクトであるhttps://github.com/xiaoymin/swagger-bootstrap-ui  ）、闊歩のUIの強化で作られた、全体的な機能は、より豊かであるように思われます。効果を確認するには、

プロジェクトのデバッグURLアドレスは、もともと独自のサービスに基づいていた、私は、デバッグ・インタフェースをサポートするためのURLアドレス登録サービス、登録サービスに変更します。調整後送信元アドレス：  https://github.com/ronwxy/swagger-bootstrap-ui

2.闊歩API登録サービス

プロジェクトが闊歩-ブートストラップ-UIを統合し、サービスが1つのページに統一されたビューを登録することができるように、すべての有効なコンフィギュレーション・レジスタを受け入れるようにサービスを提供し、闊歩の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在线接口文档集中管理，有效提高前后端对接效率。

 

接口文档是前后端开发对接时很重要的一个组件。手动编写接口文档既费时，又存在文档不能随代码及时更新的问题，因此产生了像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（ "/ *"）; 

    filterRegistrationBeanを返します。
}

 

最後に、設定ファイルapplication.ymlのプロパティでのいくつかの必要なプロパティを設定し、

威張っ：
  API-タイトル：デモ＃タイトルは、一般的に項目名を書き、ドロップダウンリストボックスに表示されます
  API-説明：デモ説明、集中型の登録
  グループ名：デモプロジェクト
  のAPIベース・パッケージ：cn.jboost.springboot.swagger＃パッケージ名APIクラス
  ます。http：威張っ-レジストリパス // localhostを：11090 /闊歩/登録＃ 2は、サービス登録インターフェイスアドレスに登録されています

 

設定が完了したら、ほとんどのプロジェクトのようなインターフェイスクラス、プラス闊歩コメントを書くことができます。プロジェクトが起動すると、自動的に文書のレジストラは、ドロップダウンリストを表示するには、ページをリフレッシュするために、レジストラに登録されます。

4.まとめ

本論文では、闊歩のUIを闊歩 - ブートストラップ-UIプロジェクトの実施の強化されたバージョンに基づいて、集中管理インターフェースのマニュアルを紹介します。この実現では、すべての闊歩オンラインインターフェースのドキュメントの集中管理は、フロントとリアエンドバットの効率を向上させます。