Restful APIドキュメンテーションのヒント

10月 31, 2022 7 ミン

内容

API のドキュメントの完全性は、その有用性を決定します。REST APIのドキュメントを書く際には標準的な手順を採用し、すべての読者にとってより読みやすく、理解しやすいマニュアルを作成する。手順、カテゴリ、結果の種類、パラメータなどの情報を含む、APIについて学ぶために必要なすべてを網羅したクイックリファレンスガイドは、REST APIのドキュメントによって実現されます。この記事では、REST APIについて、REST APIドキュメントの書き方、ドキュメントを書くためのヒントやツールについてご案内します。

REST APIについて

REST APIを利用することで、さまざまなインターネット上のアプリケーション同士が簡単に通信できるようになります。あるプログラムを利用する際に、別のプログラムからデータを取得することができます。時間がかかり、安全性が低い従来の方法の代わりに、RESTful APIを使用することができます。APIを使用すると、ユーザーインターフェイスに関与することなく、システムからデータを取得することができます。

RESTは、ネットワーク化されたハイパーメディア・プラットフォームやその他のWeb技術のための、一般的なアーキテクチャ設計およびプログラミング手法である。例えば、InstagramのAPIは、プログラマーが顧客のオブジェクトを取得するように要求すると、ユーザーのステータス、ID、接続、共有ツイートを返します。API統合のおかげで、これは実現可能なのです。

APIドキュメントはどのように書けばいいのか？

より良いドキュメントは、ガイドと教育ツールの両方の役割を果たすべきで、開発者は一目で必要な詳細を素早く見つけることができ、ドキュメントを確認することで検討している技術の取り入れ方を学ぶことができる。その結果、適切なドキュメントは、簡潔かつ見やすく、次のようなものを提供する必要があります。

その技術やアイテムが何をするのかの詳細な説明
問題点や注意点など、開発者にとって重要な内容を伝えるコールアウト。
対応するメディアタイプのコンテンツが含まれる呼び出し例
この技法で使用される変数のチェックリストと、その種類、特定の構造化要件、必要性の有無に関する情報。
メディア型bodyをもつ応答の例
必要なコードをすべて含む、複数の言語によるスクリプトのサンプル（Java、.Net、Ruby など）。
SDKインスタンス
サービスやプロシージャに到達するために、その方言用のSDKをどのように使用するかを示しています。
APIリクエストをテストし試すための貴重なアクティビティ（API Console、API Notebook）
コードのあるクエリや状況はよく質問されます。
関連するWebサイトへの参照（他の例、ブログ、その他）

RESTful APIドキュメントを書くための最高のヒント

ドキュメントを書くための戦略を練る

ドキュメント作成を始める際には、徹底した戦略を立てる必要があります。その結果、あなたの成功確率は上がるでしょう。REST APIのドキュメントを作成する前に、ドキュメントを作成する読者を理解しましょう。想定する読者を意識すれば、ドキュメントに適したプラットフォーム、スタイル、レイアウトを容易に選択することができます。

REST API を文書化する目的と範囲を明確に把握すれば、API の使用法を改善する適切な資料を作成することが容易になります。ユーザーの要件を考慮してREST APIを記述することで、よりユーザーの要件に合ったドキュメントを整理することができます。

消費者は、APIを使用する際に、操作シナリオの心象風景を持っていることを忘れないでください。例えば、ユーザーはAPIドキュメントをコスト、返品、顧客、支払い方法を提供している場合はデビットカードなどを考慮すると思われます。

したがって、そのようにドキュメントを整理することで、論理的になります。Stripe APIのドキュメントを勉強することを検討してください。彼らはAPIを論理的にグループ化する前に、適切なイントロダクションを与えてくれる。GitHubは、"GitHubの情報、問題、メンバー "のセクションがあり、よく整理されたRESTful APIドキュメントのしっかりとした図解を提供しています。

GitHub API docs

GitHubでは、プルリクエストやブランチなどを作成することができます。GitHubのAPIドキュメントは、オープンソースです。GitHubの最も良いところは、常に重要な方法で開発者の体験を向上させようと努力していることです。

基本的なセクションを含める

優れたRESTful APIドキュメントには、ある程度のパーツが含まれていなければならない。そのような核となる部分は、ドキュメント化されたREST APIのわかりやすさを高め、受け入れられやすさを向上させるために不可欠です。REST APIを文書化する際には、いくつかの基本的な要素を考慮する必要があります。

REST APIの紹介
ユーザー資格の取得方法
APIを使用するために必要なリソース
APIと通信する際のエラーメッセージ
使用条件

整合性を保ち、専門用語を排除する

テキスト全体で用語の使い方に一貫性を持たせることも、RESTful API ドキュメントに役立つ方法である。言語やコーディングの不一致がない、一貫した書き方をすること。内容を徹底的に校正した上で、不明確な部分や理解しにくい部分を削除する。

常に一貫した用語と語彙の標準を使用する。HTTPプロトコルやステータスコードなど、誤解を招きやすい項目名については、想像力を働かせること。例えば、REST APIを説明する場合、指定したリソースからデータを取得するためにはGET HTTP動詞を使用する必要があります。このように、既知の規範に従えば、多くの説明文を書く必要はありませんし、文書も読みやすくなります。また、APIの説明で技術的な言葉を使いすぎるのも避けましょう。主要な読者の要求に応えられるような、わかりやすい言葉を使うようにしましょう。

インタラクティブな図解を追加する

ほとんどの開発者は、ドキュメントで読んだことが効果的かどうかをテストすることを楽しみます。開発者の多くが知っているプログラミング言語では、動的なサンプルプログラムを含めるようにしましょう。そうすることで、API開発の複雑さが軽減される。

動的なREST APIの例を含めることは、APIを利用する際の学習曲線を低くするための効果的な手法である。さらに、ユーザーが提案を提出し、どのような回答が得られるかを調べるために使用できるテスト情報を含めることもできます。

REST API を文書化する場合、実際の例以外の資料を含めることができます。これは、説明書で提供される情報を超えて、ユーザーがAPIを最大限に活用できるよう支援するものです。アカウント設定ガイド、フレームワーク、開発ツール、セミナーなどは、APIの説明を補強するために使用できる資料の一部です。

エントリーレベルのポジションのために書く

ドキュメントを作成するのは、開発者ではなくプロのライターであることが多い。これは、テクニカルライターが、技術的な概念を理解しやすい言葉に解釈することを専門としているためです。しかし、多くのテクニカルライターはマニュアルに技術的な語彙を使用します。各APIは、特定の読者を想定して開発されています。

APIドキュメントは、開発者、判定チーム、オブザーバーなど、幅広い視聴者を対象にしている。開発者はドキュメントに関与する。エンジニアやCTOなどの判定チームは、そのAPIが適切なマッチングであるかどうかを素早く理解し、テックライターや記者、ライバルなどの観衆は、そのAPIが適切なマッチングであるかどうかを素早く理解する。

これらの人々は明確な任務と才能を持っているので、あなたのREST APIドキュメントを見るときはリラックスする必要がある。その結果、最も経験の浅い消費者に焦点を当てるべきでしょう。REST APIを文書化する際に上記のテクニックを適用し、REST API文書がAPI知識の程度が異なる人々にも理解可能であることを保証してください。

RESTfulなAPIドキュメントを生成するための最適なツール

テクニカルドキュメントは、Restful API用のツールを使って効率化されてきた方法です。テクニカルライターは、コーディングに慣れていれば、これらのRESTAPI文書作成ツールを使って技術出版物を作成することができます。APIドキュメンテーション作成ツールは広く普及しているため、最も有名な制作者は無料でOpenAPI v3に対応しているものを以下に紹介する。テクニカルライターは、これらのリソースを使用してREST APIドキュメントを作成します。

SwaggerHub

SwaggerHub は、Rest API ドキュメントを合理化し、迅速化するために作成されたデジタル API ドキュメントプラットフォームで、チームや企業に最適です。APIエディタを使えば、OpenAPI仕様（）（旧名：）に素早く対応することができます。OAS Swagger

SwaggerHub

その機能の一部を紹介します。

効果的なエラーレポートと言語の自動完成
標準を継続的に強化する統合されたAPI設計ガイドライン
API間で普遍的なOAS構文を保存し活用するためのウェブサイト
リアルタイムの問題追跡とコメント
優れた開発者体験を提供

Redocly

REST API ドキュメンテーションのプロセスは、Redocly's Workflows ソリューションを使用して自動化されています。特別仕様のソフトウェアに保存し、監査手順を確立し、様々な設定に配信することで、仮想化されたドキュメントを使用してプログラムコードのようにドキュメントを処理することができます。Redoclyまた、のユーザー権限、試行確認などの認証機構により、チームが効果的かつ安全に共同作業を行うことをさらに保証することができます。 Redocly の表示能力もユニークな機能です。修正した内容を公開する前に評価・議論してもらうために、各プロジェクトやパッチリクエストのプレビューを行うことができます。

Stoplight

Stoplight's REST API writing utilityを使用すると、APIドキュメントをデジタルで構築し、提供することができます。このソフトウェアを使用すると、内部および外部で一般に配布できる動的なREST APIドキュメントを生成することができます。JavaScript、Python、Javaなど、さまざまなプログラミング言語で作成されたハウツー記事、取扱説明書、コードサンプルなどを組み込むことができます。

REST APIドキュメントソリューションの大きな特徴の一つであるStoplightにドキュメントを掲載することができます。これにより、サーバーの運用に煩わされることなく、コネクターを使ってパーミッションの管理やメトリクスのトラッキングを簡単に行うことができます。

ReadMe

APIドキュメントは、ReadMe を使って、開発者のためのダイナミックなセンターになることができます。このハブでは、コード例を自動的に作成したり、ReadMeエディタで資料を変更したり、推奨編集を統合したり、ディスカッションボードで問い合わせに応じたり、さまざまなことが可能です。

ReadMe の最も大きな利点の1つは、ページ訪問、APIリクエスト、APIの失敗、さまざまなWebサイトへのクエリなどの分析を行うことで、アプリケーションプログラミングインターフェースやREST APIドキュメントが時間と共にどのように使用されているかを見ることができることです。これらの指標を利用して、担当者はどこに努力を集中させれば改善できるかを判断することができます。

apiDoc

apiDoc と呼ばれるオープンソースの REST API ドキュメントソリューションは、API の詳細を含むコードベースからドキュメントを生成します。実質的にすべてのプログラミング言語と、互換性があります。apiDoc では、API のエディション間で何が変更されたかを観察することができます。これにより、APIのバージョン管理として知られる、APIの更新をきれいに処理することが容易になる。

DapperDox

DapperDox は、RESTful API ドキュメントライターが、REST API ドキュメントライターのために、ライターが望む自由と開発者が必要とする読みやすさを提供するために開発されました。このWeb APIドキュメントのソリューションは、ライターが制作した説明サイトに適切な資料を追加できるため、分かりやすい説明とWeb API標準を含む首尾一貫したドキュメントのコレクションを生成するのに理想的です。さらに、必要に応じて相互参照したり、さまざまなAPI要件を商品群として記述したり、テーマを選択して論文をさまざまにフォーマットしたりすることもできます。

DocGen によってLucyBot

LucyBot'のDocGen を使って、動的な API ドキュメントを生成・管理することができます。このプログラムは、すべてのAPIメソッドと引数についてドキュメントを作成し、即座に返信します。APIコンソールを作成し、クリエイターやユーザーがAPIのトライアルリクエストを行うことで、APIの調査、トラブルシューティング、理解をより深めることができます。また、ユーザーが選択したソフトウェア言語で特定の仕事を完了するために、どのようなコーディングを作成し、どのような段階を踏まなければならないかを正確に示すプロセスを作成することもできる。

AppMaster

REST API

他のプラットフォームとは異なり AppMasterは、開発者が手動で REST API ドキュメントを作成し、それを更新する必要性を排除します。このプラットフォームは、各アプリケーションのREST APIドキュメントをSwagger (OpenAPI) 形式で自動的に生成・更新し、さらに各サーバーアプリケーションにSwagger UIを搭載して、サードパーティの開発者が生成したアプリケーションと容易に統合できるようにします。また、AppMaster プラットフォームでは、REST API ドキュメントを生成する際に、各エンドポイントの説明文にエンドポイントや関連するビジネスプロセスの説明が自動的に含まれるため、開発者がドキュメントを作成・更新する必要が完全になくなります。