APIインタフェースの文書管理ツール、あなたが知っている、何？

先週は、誰かがアクセス闊歩するかどうかを検討し、私のGithubのオープンソースプロジェクトで1つの問題に言及しました。さて、今日は他のインタフェース文書化ツールとの比較を行うために闊歩を使用しますが、その時点のAPIインタフェースの文書化ツールの事について話をします。今日は、この十年の最後の最後開発面では、APIインタフェースのドキュメント管理ツールは、ますます重要になってきています。完全なインタフェースの文書の前と後のAPIが大幅に、端末開発のコラボレーションの効率を高めることができます。

画像

管理ツールを文書化するために、現在の市場は比較的良好な界面は何ですか？最後に闊歩APIインタフェースの文書化ツール、それについてどのように、私は一般的に要約！

一、闊歩

闊歩といえば、彼は本当に彼が自動的に非常に便利な、APIインタフェースのドキュメント、オンラインデバッグを生成することができ、アーティファクトの開発者が発明しています。闊歩公式文書：  https://swagger.io/。プロジェクトアクセス：ポンポン依存：

<!-- swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency> 

構成情報：

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter { @Bean public Docket buildDocket() { Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()); docket = docket.select() .apis(RequestHandlerSelectors.any())//controller路径 .paths(PathSelectors.any()).build(); return docket; } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } private ApiInfo buildApiInf() { return new ApiInfoBuilder() .title("RestAPI Docs") .termsOfServiceUrl("http://www.github.com/kongchen/swagger-maven-plugin") .build(); } } 

（例えば）構成でコントローラ。

@Api(value="客户API",tags={"客户API"})
@RestController
@RequestMapping("/api/customer/") public class CustomerController { /** * 更新采购商资料 * * @return * @throws Exception */ @ApiOperation(value="更新商户信息", notes="根据Customer对象更新,SON格式：{\"id\":1,\"customerType\":\"..\",...}") @ApiImplicitParam(name = "Json", value = "", dataType = "Json",required = true) @ResponseBody @RequestMapping(value="update", method=RequestMethod.POST, produces = {"application/json;charset=UTF-8"}) public JSONObject updateCustomer(HttpServletRequest request) throws Exception{ //TODO 代码逻辑 } } 

プロジェクト、オープン闊歩、インタフェースを起動します。http://192.168.1.101:9001/swagger-ui.htmlを、

画像

ただ、インターフェイス設定を見てみましょう。

画像

闊歩特に簡単にアクセスでき、またオンラインで入手可能なデバッグ。闊歩が、それは確かに非常に高速なハードウェアであり、我々は彼の長所と短所を見てください。

闊歩する利点は次のとおりです。

1、最大の利点である時間手書きインタフェースの文書の多くを節約。

図2に示すように、文書は、ポストマンインタフェースパラメータを使用して、設定処理を保存、直接インターフェース回線テストを生成することができ、そしてリクエストのパラメータは、パラメータが一目を返します。

図3に示すように、インタフェースモジュールは、ディスプレイ、明確な構造に従って分類されています。

****闊歩の欠点は次のとおりです。

1は、より明確なコード生成されたインタフェースのマニュアルのノート、より多くの書かれた多くのコメントを記述する必要があります。

ケース2は、複雑な機能のために、関数が複数のモジュールを一緒に必要となる、FBIのテストは非常に面倒なことになりましょう。闊歩は、カスタムインターフェース文書はインタフェースと機能を使用する必要性を示すものではありませサポートしていません。

3、对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 @ApiResponse注解用来说明返回结果，但是这个使用并不方便，而且如果返回的并不是对象的时候(如 Map)，就无法实现给每一个返回字段的说明；

4、无法测试错误的请求方式、参数等。如接口指定使用 POST 请求，则无法使用 swagger 测试 GET 请求的结果，也无法自定义 Header；

5，分布式开发环境中，一个项目往往有多个接口服务（比如电商项目有app，pc，后台三个接口服务）。每一个接口服务都对应一个独立的swagger文档，不能实现统一整合。

二，apizza

Apizza也是我们项目中使用过的，是从Swagger 转到Apizza。而却他是极客专属的api协作管理工具，免费的团队协作，在线模拟调试，快速生成api文档，导出离线版文档。

image

项目Api接入：

只需在Apizza官网（https://apizza.net）申请账号，创建项目，并手写添加接口文档。

主要功能

1. api跨域调试量身定制的chrome插件，本地，在线接口，都可以调。

2. 云端存储，企业安全版支持本地数据中心。

3. 一键分享，与团队共享你的API文档。

4. 支持Postman，Swagger格式 导入Postman/Swagger Json 生成文档。

5. 导出离线文档，部署本地服务器。

6. api Mock 根据文档自动生成返回结果，提供独立URL方便前端测试。

7. 支持多种文档 http接口文档，markdown说明文档。

Apizza接口文档工具有一个很大不足的地方，那是Apizza个人免费版有人数****限制，所有超过8人的团队如果想免费用，你是不用考虑Apizza的。如果你看到有文章或公众号上说Apizza是免费的，那简直是胡扯，他肯定没用过。当然如果你不缺钱，可以付费开通企业版。我们团队也是用了半年多Apizza，后来由于人员增加，Apizza里又无法再新添加新成员，迫使我们不得不放弃Apizza。

image

三，Yapi

Yapi是去哪儿网开源的一款接口管理工具。Yapi旨意将接口作为一个公共的可视化的方式打通前端、后台、测试环节，整合在一块，共同使用维护，提高接口的维护成本。Yapi是一款免费开源的Api接口文档工具，需要下载部署在自己的服务器上。Yapi也是我们现在正在使用的接口文档工具。

image

image

主要特点如下：

• 权限管理 YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求；
• 可视化接口管理 基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率；
• Mock Server 易用的 Mock Server，再也不用担心 mock 数据的生成了；
• 自动化测试 完善的接口自动化测试,保证数据的正确性；
• 数据导入 支持导入 swagger, postman, har 数据格式，方便迁移旧项目；
• 插件机制 强大的插件机制，满足各类业务需求；

image

ここでは詳細に説明していないYAPIにインストールされています。YAPIは、プリインストールさnodejs、MongoDBは、Gitのアプリケーションをインストールする必要があります。今日は全体的に、これらの3人はかなり良い感じ、主に使用されるAPIインターフェースのドキュメントツールを話しました。非常に若いチームで、それは実際の需要を満たすことができます。チームの数が徐々に増加する場合しかし、私たちが闊歩からApizzaに、その後YAPI理由でツールの制限のいくつかを検討する必要があります。もちろん、上記の3つに加えて、市場では、他の多くのAPIドキュメントツールがあります。以下のような：eoLinker、ShowDoc、easydoc、同様MinDoc。具体的な使用することを、そのいずれかの操作を行い、と言いましたか？この必要性は、自分のチームによると、自分の状況に最も適したを選択します。

世間の注目のコード番号をスキャンし、関連情報を取得するキーワードを送信します。

1. 実際のソースプロジェクトは、電気の供給を受ける「Springboot」を送信します。

2. 実際の学習教材を受け取る「SpringCloud」クラウドを送信します。