背景
現在、多くの中小規模の開発チームや起業家チームは依然として API インターフェイスを逆方向に操作しています。ドキュメントを書いた後にコードを書いたり、コードを書いた後にドキュメントを補足したりしています。さらに、すべてはドキュメントに依存します。片方の口でインターフェースの記述情報をIMでやりとりするため、共同デバッグの際にフロントエンドとバックエンドが対立し、悲惨な状況になります。
もちろん、swagger、springfox、springdoc、knife4j、apifox、eolink、smart-doc など、より成熟したソリューションを使用している優れたチームも数多くあります。著者は長年の研究開発経験に基づき、上記のような国内外の複数のAPI管理ツールや実装を参照・比較しており、美しく効率的なAPIプラットフォームツールは開発者にとって非常に重要であると常々感じている。検索して比較するのに苦労した後も、さまざまな API 管理ツールは依然として作者の期待を満たしていなかったので、最終的に彼は個人的に怒りに任せて Apideploy を書きました。
デザインのコンセプト
Apideploy は、次の設計概念に従っています。
- コードはドキュメントです。API ドキュメントは、フロントエンドやテストなどと連携するために手書きドキュメントを使用するのではなく、コードを通じて自動的に生成され、コードとの同期を維持できる必要があります。
- 主流の標準に優しい。この文書は、主流の OpenAPI 2 (OAS2.0)、OpenAPI 3 (OAS3.0) およびその他のプロトコル標準をサポートする必要があり、また HTTP、WebSocket、SSE およびその他のプロトコルもサポートする必要があります。
- バージョン追跡可能。バージョンの反復ごとに、インターフェイスの変更の詳細をすばやく確認し、異なるバージョン間の相違点の比較をサポートし、ドキュメントのバージョンのロールバックをサポートできます。
- インターフェイスはモック化できます。インターフェイスのテスト、共同デバッグ、さらにはインターフェイスの自動化も製品上で直接完了できます。
- インターフェースは美しくあるべきです。フレンドリーなユーザーインターフェイスとインタラクション。
- サードパーティと互換性があります。共通の API プロトコル標準ドキュメントのインポートと共通のドキュメント形式のエクスポートをサポートします。
製品アーキテクチャ
Apideploy のコアは、API ドキュメント生成 SDK + API ホスティングおよびデバッグ プラットフォームの2 つの部分に分かれています。
API ドキュメント生成 SDK は完全にオープンソースであり、 https://github.com/apideploy-teamで参照できます 。現在、Java 言語の実装のみがサポートされています。他の言語コミュニティのユーザーは、API ホスティングおよびデバッグ プラットフォームの RESTFull API を介して貢献したり、直接接続したりできます。Java 言語 SDK は、javadoc コメントに基づいて API ドキュメントを自動的に生成し (コードの侵入はありません)、Swagger ベースの実装とも互換性があります。具体的な使用方法については、以下を参照してください。
API ホスティングおよびデバッグ プラットフォームの主な機能には、プロジェクト管理、チーム コラボレーション、権限管理、API ドキュメント ホスティング、ドキュメント デバッグ、インターフェイス データ モック、バージョン更新レコード、バージョン比較、パーソナライズされたドキュメントのエクスポート、マルチフォーマット ドキュメントのインポートなどが含まれます。 . これは、チームのコラボレーションに非常に適した、包括的な API の完全なライフサイクル管理プラットフォームです。現在、パブリック クラウドとプライベート デプロイメントをサポートしています。www.apideploy.comはパブリック クラウド ソリューションです。
ドキュメント生成原理
Apideploy は、document as codeの設計概念を提唱しているため、著者は、 Swagger実装ほど面倒ではない、コード コメントに基づくドキュメント生成方法を強く推奨しています。
コードコメントに基づいてドキュメントを生成する
コード コメントに基づいてドキュメントを生成します。Apideploy の実装は、 smart-docのオープン ソース コードを参照し、依存しています。Smart-doc は、 qdoxに基づいた優れた Java ドキュメント解析ツールです。それに基づいて API ドキュメントを変換するプロセスを簡単に実現します。コードのコメント。
Apideploy は、Java コードの注釈からドキュメントを生成するすべてのコードをオープンソース化しました。
Swagger/OpenAPI ベースのドキュメント生成
Java Web プロジェクト開発に基づく Swagger 実装では、最も一般的に使用されるオープンソース実装はSpringfox (国内のKnife4jを含む) とSpringdoc-openapiです。Springfoxは多くのユーザーがいますが、更新が停止し、springboot3.0以降のプロジェクトをサポートしなくなったようです。
Apideploy は springfox および springdoc-openapi のすべての実装と互換性があるため、前のプロジェクトで swagger プロジェクトを使用していた場合、ドキュメントのホスティングとテストのために Apideploy に切り替えるのが非常に便利です。
API ホスティングおよびデバッグ プラットフォームのプレビュー
