詳しくはRESTful APIのドキュメント管理

6301 ワード

目次

  • APIドキュメントフォーマット
  • ドキュメント管理方式
  • 注釈に基づいて実装され、コードとドキュメントが一緒に
  • Swagger
  • Api2Doc

  • APIテストツールに基づいて生成
  • Postman
  • rest-client

  • 独立した文書作成
  • RAP
  • DOClever
  • APIDOC
  • CrapApi


  • 最後の
    • に書いてあります
    規範的なインタフェースドキュメント管理方式は、コンポーネントの協同(例えば、前後の分離)の開発効率を向上させ、プロジェクトのインタフェースの説明に対してグローバルな管理視点があり、対外公開を容易に実現することができる.完全なドキュメント管理には、ドキュメントフォーマットとドキュメント管理方式の2つの部分が含まれている必要があります.以下で説明します.

    APIドキュメントフォーマット


    規範的なAPIドキュメントフォーマットは理解に役立ち、開発効率を大幅に向上させ、不要なコミュニケーションコストを削減することができます.しかし、統一されたフォーマットで制約する必要はありません(結局、異なるプロジェクトの要求が通じず、異なるアーキテクチャのスタイルも異なります)、Wordで書くのが好きな人もいれば、Markdown文法が好きな人もいます.要するに、どのようなフォーマットを採用しても、APIインタフェースを完全に、明確に説明しなければならない(例えば、インタフェース機能、方法定義、パラメータの意味、戻りフォーマットなど).チームにAPIドキュメントフォーマット仕様が統一されていない場合は、アリの金服APIドキュメントフォーマットの例を参照して設計できます.

    ドキュメント管理


    RESTFul APIドキュメント管理方式(生成,メンテナンス)は大きく3種類に分けられる.

    注釈に基づいて実装され、コードとドキュメントが一緒になります。


    注釈に基づいてドキュメントを生成する利点は、コードとドキュメントが一緒にいて、ドキュメントを単独で維持する必要がないことです.欠点も明らかで、ビジネスコードにドキュメント注釈を埋め込む必要があり、コードが乱れているように見えます.注釈方式に基づいてドキュメント管理を実現する典型的なツールは、Swagger、Api 2 Docである.

    Swagger


    Swaggerは人気のあるRESTFulドキュメント生成ツールですが、比較的規範的で完璧なドキュメントを生成する必要がある場合は、注釈を書きすぎて、煩雑で、詳細は以下の通りです.https://swagger.io/. Swaggerによるインタフェースドキュメントの管理については、次のリソースを参照してください.https://github.com/swagger-apiSwagger GitHubプロジェクト公式サイトhttps://www.jianshu.com/p/33c28a65deb8Swagger-強力なAPIドキュメントツールhttps://blog.csdn.net/zhangxin09/article/details/82699353Swagger 2(Open API v 3.0)Javaドキュメント生成ガイド(上)https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.htmlSpring BootプロジェクトでのSwaggerドキュメントの使用https://blog.csdn.net/u014745069/article/details/80246803Swagger使用——インタフェースパラメータ注記の使用欠陥https://blog.csdn.net/xiaojin21cen/article/details/78654652swagger 2注記説明https://blog.csdn.net/cy921107/article/details/82761575Swagger 2 JSONObjectパラメータについてAPIドキュメントに詳細パラメータおよびパラメータ説明を表示するhttp://www.voidcn.com/article/p-bxgydblc-bnz.htmlSwaggerを利用して前後端分離の障害を解消するにはどうすればいいですか?https://www.cnblogs.com/softidea/p/6226463.htmlSwaggerのテーマhttps://www.cnblogs.com/ceshi2016/p/10511959.htmlSwagger Annotation詳細(推奨コレクション)

    Api2Doc


    Api 2 Docの原理はSwaggerに似ているがSpring Bootフレームワークに基づいている.現在、このツールはまだ完備していません.1.0.2バージョンの時報が間違っています.詳細は以下の通りです.https://github.com/terran4j/commons/tree/master/commons-api2docapi 2 doc公式サイト

    APIテストツールに基づいて生成


    コードとドキュメントは分離されていますが、ドキュメントを単独で作成する必要はありません.インタフェーステスト時にドキュメントを生成できます.

    Postman


    Postmanは、要求に従ってオンラインで閲覧可能なAPIドキュメントとして公開することをサポートしており、権限と機密性を考慮する必要がある場合は適切ではない可能性があります.http://book.crifan.com/books/api_tool_postman/website/postman_api_doc/preview_publish_api_doc.htmlAPIドキュメントのプレビューとパブリッシュ

    rest-client


    rest-clientは個人がオープンソースのpostmanのようなREST APIテストツールであり、APIに基づいてオフラインAPIドキュメントを直接生成し、Java Swingに基づいて作成されたGUIインタフェースに基づいている.https://github.com/Wisdom-Projects/rest-client

    独立した文書作成


    独立してAPIドキュメントを維持するのは最も簡単な方法ですが、欠点も明らかです.それは、コードとドキュメントの同期が遅れたり、ドキュメントが期限切れになったりする可能性があります.独立したAPIドキュメントは、必要に応じてオンライン(現在は多くのオンラインAPI管理システムが存在する)またはオフライン(例えば、Execelテーブル、MarkDown構文、さらにはWord)のフォーマットで作成できます.
    以下に、WebベースのAPI管理ツールをいくつか紹介します.

    RAP


    公式サイト:https://github.com/thx/RAPRAPはアリオープンソースのWebインタフェース管理ツールで、オープンソースは無料で、インタフェースの自動化をサポートして、MOCKデータの自動生成、自動化テスト、企業レベルの管理.RAPの機能は比較的フルですが、JSON形式の要求パラメータはサポートされていません.

    DOClever


    DOClevenはビジネスのAPI管理システムで、公式サイト:http://doclever.cn/controller/index/index.html. オープンソースバージョンがあります.詳細は、次のとおりです.https://github.com/sx1989827/DOClever. DOCleverは機能が非常に強力で全面的だと言われていますが、オープンソースバージョンの裁断は本当に簡素すぎて、直接使うのには向いていません.それに基づいて二次開発をすることができます.オープンソース版のインストールではnpmを使用しないことをお勧めします.起動時に各種のエラーが発生し、ソースコードを使用してインストールしてもこの問題はありません.
    #    DOClever        MongoDB
#         DOClevere
$ git clone https://github.com/sx1989827/DOClever.git
$ cd DOClevere
$ npm start

    起動エラーの場合は、nodeバージョン8.11.1を使用することを推奨します.

    APIDOC


    APIドキュメントを個別に作成する別のツールはAPIDOCです.公式サイト:http://apidocjs.com. APIDOCは、通常のインタフェースドキュメント管理ツールに比べて、比較的奇妙な道を歩んでいます.インタフェース(注:このインタフェースはビジネスインタフェースではなく、ドキュメントを生成するためのインタフェース)によってAPIを定義し、本質的にはビジネスコードの外でインタフェースドキュメントを維持します.https://blog.csdn.net/soslinken/article/details/50468896apidocを使用してRestful web Apiドキュメントを生成https://blog.csdn.net/qq_27384769/article/details/78622831apidoc使用チュートリアル-きれいなapiドキュメントを作成

    CrapApi


    CrapApiは現在オープンソース製品の中で最も満足しており、基本的なAPIドキュメント管理は比較的包括的であるが、MOCKテストのサポートはまだ弱い.しかし、メリットとデメリットがあり、オープンソースシステムにとって、コア機能はすでに悪くありません.https://gitee.com/CrapApi/CrapApi . CrapApiのインストールは非常に簡単で、それ自体は伝統的なJava Webプロジェクトであり、最終的にはwarファイルにパッケージ化されるので、warパッケージをTomcatのwebapppsディレクトリの下に置くだけでアクセスできます.注意:CrapApiソースコードのSQLスクリプトはツールを使用してエクスポートされるため、中のコメント(主に/***/形式のコメント)は一部のSQLツールの下でエラーが発生する可能性があり、直接削除すればよい.

    最後に書く


    APIのドキュメント管理方式は多種多様であるが、完璧に違いない.それぞれに長所と不足があり、主に:1に体現されている.コードの中でドキュメントを維持して、Javaの中で注釈を通じて完成することができて、最もコードとドキュメントの一致性を維持するのに有利で、しかし1部の比較的に完備したドキュメントを生成するために1山の注釈を追加する必要があって、これは本当の業務コードの簡潔性を汚染して、甚だしきに至っては性能の損失の欠陥があります;2.独立して文書を作成する方式は業務コードを汚染しないが、コードと文書が完全に分離するため、コードと文書の一致性を維持するコストが隠れて増加する.3.対照的に、APIテストツールに基づいてドキュメントを生成する方法は比較的折衷的であるが、ドキュメントを生成する機能はツール自体と密接にバインドされており、私有化された導入と権限管理が困難である.
    実際には、どのような方法を採用しても、ドキュメントのメンテナンスには一定の規則制度が必要であり、タイムリーな更新を保証する必要があります.「プログラマーはドキュメントを書くのが好きではありませんが、他の人にドキュメントを書くことを望んでいます」.これは開発者の共通の病気で、コードの中でドキュメント(例えば:Swagger)を維持する方法を採用しても、開発者が慣れていないか、開発者に更新ドキュメントをタイムリーに維持することを約束していない場合は、ドキュメントとコードの同期の問題を解決することはできません.結局、これは人が駆動する必要がある(パラメータの変更、方法の増加は同様に対応するドキュメント注釈を注入する必要がある).したがって,APIドキュメントのメンテナンスに万能なソリューションはなく,どのドキュメントメンテナンス方式を採用しても対応する制度が強制的に実行されなければならない.そうしないと,どんなに良いツールがうまく使えなくても意味がない.どのようなドキュメント管理方式を選択するかは、アーキテクチャの好みに依存したり、プロジェクト自体の実際のニーズ(例えば、対外公開が必要かどうかなどの要因)に基づいて適切な案を選択したりすればよい.結局、どのような手段を採用しても目標を達成する1つのツールにすぎず、どのように効率的に使用するかが重要である.
    【参考】https://www.jianshu.com/p/be32a38f408dAPIインタフェース管理の道https://blog.csdn.net/vimx86/article/details/78381838インタフェースドキュメント管理スキームhttps://hacpai.com/article/1519833837647API管理ツールSwaggerとRAPの比較https://www.cnblogs.com/minsons/p/7133095.htmlApi管理ツール(spring-rest-docs)
    Walkableゲームマップを構築するために2次元配列を使用する
    野生の手淫事件😮 !!!