Janet Wagner 著
API仕様とAPIドキュメントの違いについてよく質問されます。そこで今日は、APIドキュメント、API仕様、API定義の違いと重要性について概説したいと思います。
APIドキュメントとは？
APIドキュメントは、APIのリファレンスマニュアルであり、APIコンシューマにAPIの利用方法を伝えます。APIドキュメントは、人間、通常は開発者が読んで理解することを目的としています。開発者がAPIを快適に利用できるようにするためには、適切に設計され、包括的で、わかりやすいドキュメントを提供することが重要です。優れた開発者体験 (DX) は、APIの成功の可能性を高めます。開発者がAPIドキュメントに従えない場合、より良いドキュメントと統合が容易な別のAPIを見つける可能性が高いでしょう。また、優れたドキュメントは、新しいAPIコンシューマのオンボーディングにかかる時間を短縮するのに役立ちます。開発者が必要なすべての情報を入手できれば、御社にメールを送ったり、カスタマーサービス部門に電話したり、フォーラムに投稿して助けを求めたりする必要がなくなります。
優れたドキュメントには多くの要素が含まれており、ここにすべてを挙げることはできません。しかし、優れたAPIドキュメントには、クイックスタートガイド、チュートリアル、開発者がAPI呼び出しを試せるインタラクティブなドキュメントなどが含まれます。APIドキュメントの生成と保守には多くのツールが利用できます。これらのツールの多くは、API定義ファイルから静的およびインタラクティブなAPIドキュメントの両方を自動的に生成できます（これについては記事の後半で説明します）。
APIドキュメントには、すべての呼び出し、すべてのパラメータ、および各呼び出しの応答の例を提供する必要があります。Java、JavaScript、PHP、Pythonなどの一般的に使用される言語のコードサンプルを含める必要があります。ドキュメントには、各APIリクエストの説明とエラーメッセージの例を提供する必要があります。また、APIドキュメントが積極的に保守され、常に最新の状態であることが重要です。
API仕様とは？
API仕様という用語は、API定義と互換的に使用されることがよくあります。これらの用語には多くの類似点がありますが、異なるエンティティです。API仕様は、APIがどのように動作し、他のAPIとどのように連携するかについて、幅広い理解を提供します。APIがどのように機能し、APIを使用するときに期待される結果を説明します。API仕様の良い例は、OpenAPI仕様です。この仕様の最新バージョン（3.0.1）は、GitHubで確認できます。
ある意味、OpenAPI 3.0.1ドキュメントもAPIドキュメントですが、API仕様はAPIがどのように動作し、APIから何を期待できるかを説明します。そして、GitHub上のOpenAPI Specificationドキュメントはまさにそれを実現しています。ドキュメントには、多くのAPIオブジェクト、値、パラメータ、オブジェクトがどのように呼び出されるか、各オブジェクトが何をするかについて記述されています。また、オブジェクト間の関係と、各オブジェクトがどのように使用できるかも示されています。
たとえば、リクエストボディオブジェクトのセクションを見ると、このオブジェクトが何をするか、固定フィールドの説明と型、およびリクエストボディの例に関する情報が見つかります。リクエストボディオブジェクトがどのように機能し、この機能を使用するときに何を期待できるかがわかります。API仕様は、APIがどのように設計されているか、およびAPIがサポートするデータ型を示すものでもあります。
OpenAPI（以前のSwagger仕様）は、いくつかのAPI仕様言語の1つです。その他にRAMLやAPI Blueprintがあります。これらのAPI仕様言語が1つのAPI仕様言語であるOpenAPIに収束する動きがあることは注目に値します。
API定義とは？
API定義は、APIがどのように編成され、どのように機能するかを理解させるという点でAPI仕様に似ています。しかし、API定義は、APIの人間による利用ではなく、機械による利用を目的としています。API定義は、APIがどのように機能し、他のAPIとどのように連携するか、および期待される結果を機械可読な形式で提供します。APIを定義し、APIの構造を概説することに焦点を当てています。
API定義は、自動化ツールにとってのベースラインとしてよく使用されます。API定義は、APIドキュメント、コードサンプル、SDKを自動的に生成するために使用できます。API定義ファイルからAPIドキュメント（静的およびインタラクティブ）を生成するツールの例としては、SwaggerHubやSwagger Inspectorがあります。API定義からサンプルコードとSDKを自動的に生成できるツールの例としては、REST UnitedやSwaggerHubがあります。
API定義は、仮想APIテストのためにモックサーバーにインポートすることもできます。API定義ファイルのインポートを許可するモックサーバーおよびAPIテスト用の多くのツールの中には、SoapUIやSwaggerHubがあります。
API定義は、インタラクティブドキュメントやSDKなどのAPIの成功を保証できる自動化ツールを動かすために使用できるという点で重要です。一部の開発者は、仕様言語の1つに基づいてAPI定義を最初に作成し、次にAPIのコードを記述するスキーマファーストAPI設計を提唱しています。
すべて関連しているが異なる
APIドキュメント、API仕様、API定義はすべて関連していますが、それぞれ異なるエンティティです。そして、これらそれぞれが重要な目的を果たします。
ドキュメントは、開発者や他のAPIコンシューマにAPIの使用方法を伝えます。結局のところ、開発者がAPIの使用方法を知らなければ、APIが成功することはできません。
API仕様は、APIの機能と期待される結果について幅広い理解を提供します。仕様は、主にAPIの設計または設計思想に関するものです。API設計と機能は、APIをアプリケーションと統合するかどうかを選択する際の重要な要素です。
そして最後に、API定義は、APIの機械による利用と、自動APIドキュメントやSDKジェネレーターなどの自動化ツールで使用するための機械可読形式の提供に関するものです。
APIドキュメント、API仕様、API定義はすべて、APIの成功の鍵となります。
お読みいただきありがとうございます！より多くのAPIリソースをお探しですか？Swaggerニュースレターを購読してください。毎月、最高のAPI記事、トレーニング、チュートリアルなどを含むメールを受け取ります。購読する