クラウドネイティブな方法でアプリケーションを開発しようとしています。私は自分のアプリケーションのAPIファーストデザインをしようとしています。
どのAPIドキュメントツールを使用する必要がありますか? APIファーストコントラクトに適しているのはどれですか?どちらがどこに適しているのでしょうか?
どちらの形式もAPIファーストのアプローチに適していると思いますので、好み(マークダウンとyaml/jsonベース)またはツールの制限の問題です。
https://help.apiary.io/api_101/choosing-format/ で簡単な要約を読むことができます。
どちらのフォーマットもオープンソースであり、それらを中心に構築された優れたコミュニティとツールがあります。
- SwaggerはYAML(またはJSON)形式であり、解析が容易であることに重点を置いており、拡張機能と統合の幅広いオプションがあります。
- API Blueprintには、Markdown、MSONに近い構文が付属しており、すべてのApiaryツールとオープンソースツールが完全にサポートされています。
どちらも、設計優先のアプローチで幅広いAPIアーキテクチャのセットを記述できるようにする必要があります。 Swaggerには、コードから説明を生成するためのツールが付属しています。 APIブループリント構文により、ハイパーメディア/ RESTAPIの記述が容易になります。
API Descriptionの世界に慣れていない場合は、APIブループリントから始めることをお勧めします。