Insomniaを使用してRESTAPIのドキュメントを作成する方法

著者はCOVID-19救済基金を選択し、 Write forDOnationsプログラムの一環として寄付を受け取りました。

序章

このチュートリアルでは、 OpenAPI仕様（v3）を使用してAPIを文書化します。 OpenAPIファイルは、OpenAPI仕様に準拠したJSONまたはYAMLファイルです。この仕様は、JSON / YAMLファイルに含める必要のあるフィールドと、それをホストするために使用するドキュメントサービスにどのように反映されるかを定義します。多くのサービスはOpenAPIをサポートしているため、APIドキュメントの形式を変更することなく、複数のサービスを選択して使用したり、使用したりすることができます。

ドキュメントを作成するには、 Insomnia を使用します。これは、無料のオープンソースアプリケーションであり、APIをテストし、リアルタイムでドキュメントを設計できます。サイドプレビュー。 InsomniaはJSONをサポートしていませんが、YAMLを簡単に作成できます。 YAMLはAPIドキュメントに適しています。これらのドキュメントは非常に大きくなる可能性があり、JSONドキュメントは雑然として読みにくくなるためです。

最後に、多くの企業で使用されているオープンソースアプリケーションであるRedocを使用してAPIドキュメントをホストします。 Redocは、生成したOpenAPIドキュメントを取得し、ドキュメントの見栄えが良くインタラクティブなバージョンを表示するHTMLページを提供します。また、Redocで生成されたサイトを GitHub Pages にデプロイします。これは、GitHubによる無料のウェブサイトホスティングソリューションです。

このチュートリアルでは、OpenAPIの詳細を学び、InsomniaのOpenAPI仕様に従ってAPIを文書化し、この文書をRedocを使用してGitHubPagesでホストします。

前提条件

このチュートリアルに従うには、次のものが必要です。

ドキュメント化するRESTAPI。独自に作成したい場合は、DigitalOceanコミュニティサイトでチュートリアルを確認できます。このチュートリアルでは、JSONプレースホルダーAPIを使用します。
不眠症をダウンロードしてローカルマシンにインストールしました。
NodeJSv12以降がローカルマシンにインストールされています。
ドキュメントから取得できるYAMLに精通していること。
MDN WebDocsから取得できるバックエンドWeb開発の経験。
GitHubアカウントとこのプロジェクト用に作成された新しいリポジトリ。 GitHubのクイックスタートガイド新しいGitHubリポジトリの作成に従って、新しいリポジトリを作成できます。また、GitHubにプッシュできるように、gitcliツールをインストールする必要があります。

ステップ1—APIを理解する

このステップでは、APIが受け入れるルートと、それに関連するパラメーターと応答を確認します。他の人のためにAPIを文書化する予定であり、将来この文書を参照する可能性もあるため、文書化する必要があるすべてのことに注意することが重要です。 OpenAPIを使用すると、各APIルートのリクエスト本文、ヘッダー、Cookie、さらには可能な応答を定義できます。

このチュートリアルでは、無料のモックAPIである JSON PlaceholderAPIを使用します。このAPIは非常に大きいため、このチュートリアルでは /postsセクションのみを文書化します。

次の表は、このチュートリアルで文書化する5つのルートのそれぞれの方法、ルートパス、および説明を示しています。テーブルなどを作成すると、ルートを忘れないようにするのに役立ちます（APIが大きい場合に発生する可能性があります）。

方法	ルート	説明
得る	`/posts`	すべての投稿を取得
得る	`/posts/:id`	単一の投稿を取得
役職	`/posts`	投稿を作成する
PUT / PATCH	`/posts/:id`	投稿を更新する
消去	`/posts/:id`	投稿を削除する

APIで何ができるかがわかったので、次はInsomniaでAPIの文書化を開始します。

ステップ2—不眠症プロジェクトの作成

このステップでは、Insomniaプロジェクトを作成します。 Insomniaプロジェクトには、OpenAPIドキュメント、API用に作成したテスト、および作成したリクエストが含まれています。インターフェイスは、デザイン、テスト、およびデバッグの3つのタブに分割されています。このチュートリアルでは、[デザイン]タブに焦点を当てます。

Insomniaアプリを開き、ダッシュボードに移動します。 Insomniaウィンドウの右上にあるCreateボタンをクリックして、新しい Design Document を作成し、名前を付けます。このチュートリアルでは、json-placeholder-docs.yamlを使用できます。

注： YAMLは設計上、インデントとしてスペースのみを受け入れます。ただし、不眠症はデフォルトでタブ付きのインデントです。これは後のアップデートで修正される予定ですが、今のところ、右上の歯車アイコンをクリックするか、Ctrl/Cmd + ,を押して、環境設定を開きます。 フォントセクションで、タブでインデントのチェックを外し、設定ウィンドウを閉じます。これにより、Insomniaはタブの代わりにスペースを使用するようになります。

次のスクリーンショットに示すように、3つのペインが表示されます。最初のペインには、APIのルートや定義したコンポーネントなど、ドキュメントの概要が表示されます（これらについては後で詳しく説明します）。中央のペインには、YAMLでOpenAPIドキュメントを作成するために使用するコードエディターが含まれています。このエディタはまた、エラーを自動的に検出し、下部に通知します。最後に、右側の最後のペインは、ドキュメントのリアルタイムプレビューです。使用するOpenAPIのバージョンをInsomniaに通知する必要があるため、エラーが表示されます。

[デザイン]タブのコードエディタで、openapi: 3.0.3という行を追加します。これは、使用するOpenAPI仕様のバージョンを示しています。執筆時点では、最新バージョンは3.0.3です。必要に応じて、これを新しいバージョンに自由に変更してください。

画面は次のようになります。

Insomniaインターフェースに慣れてきたので、ドキュメントの作成を開始できます。

ステップ3—OpenAPI仕様の開始

このステップでは、OpenAPI仕様について詳しく学習します。 API仕様はJSONまたはYAMLファイルにすることができますが、InsomniaはYAMLのみをサポートします。使用しているOpenAPI仕様のバージョンを指定するopenapiというキーが必要です。

仕様によると、ドキュメントのルートに存在する可能性のあるフィールドは次のとおりです。

名前	タイプ	説明
`openapi`	`string`	必須。 OpenAPIスキーマのバージョン。
`info`	情報オブジェクト	必須。 APIに関する情報を含むオブジェクト。
`servers`	サーバーオブジェクトの配列	APIサーバーへの接続オプションを提供するオブジェクトを含む配列。
`paths`	パスオブジェクト	必須。 API、メソッド、リクエストボディ、パラメータ、およびレスポンスによって提供されるルートを含むオブジェクト。これは、ドキュメントの最も重要な部分です。
`components`	コンポーネントオブジェクト	再利用可能なコンポーネントが含まれています。これは、ファイルサイズを縮小し、ドキュメントをクリーンに保つことを目的としています。
`security`	セキュリティオブジェクトの配列	APIの認証メカニズムのリストが含まれています。このチュートリアルの範囲外です。
`externalDocs`	外部ドキュメントオブジェクト	APIの外部ドキュメントが含まれています

これが多すぎて取り入れられなくても心配しないでください。 securityを除いて、各プロパティについて詳しく説明します。これは、このチュートリアルの範囲外であるためです。 securityフィールドは、ルートの認証方法（たとえば、ユーザー名/パスワード、 JSON Web Token 、または oauth ）を定義しますが、JSONPlaceholderには認証機能がありません。

ステップ4—`info`オブジェクトを追加する

このステップでは、ステップ1の表を使用して、Insomniaを使用したAPIのドキュメントの作成を開始します。 infoオブジェクトから始めます。

infoオブジェクトには、ドキュメント化するAPIに関する情報が含まれています。これには、APIのtitle、version、APIのdescription、ナレッジベースへのリンク（documentation）、およびその用語が含まれます。 -サービス（tos）。

仕様によると、これはinfoオブジェクトがどのように見えるかです。

名前	タイプ	説明
`title`	`string`	必須。 APIのタイトル。
`description`	`string`	APIの簡単な説明。ここでマークダウンを使用できます。
`termsOfService`	`string`	APIの利用規約へのURL。
`contact`	連絡先オブジェクト	公開されたAPIの連絡先情報。
`license`	ライセンスオブジェクト	公開されたAPIのライセンス情報。
`version`	`string`	必須。 OpenAPI仕様ではなく、ドキュメントのバージョン。

infoフィールドには、ドキュメントのtitleとドキュメントのversionの2つの必須プロパティがあります。これらは、APIアプリケーションのバージョンと同じである必要があります。他のフィールドは、APIについてユーザーに通知するためにあります。

次に、最もよく使用される3つのフィールドtitle、description、およびversionを使用して、infoオブジェクトをドキュメントに追加します。 Insomniaアプリで、次のYAMLコードをDesignタブエディターに追加します。

info:
  title: JSONPlaceholder
  description: Free fake API for testing and prototyping.
  version: 0.1.0

JSONPlaceholderはバージョン番号を公開しないため、これはランダムなバージョン番号です。前の手順の指定に従って、infoオブジェクトに他のフィールドを自由に追加してください。

警告：YAMLはそのインデントについて非常に慎重です。スペースでインデントする必要があり、インデントサイズはドキュメント全体で一貫している必要があります。

APIに関する基本情報を含むinfoオブジェクトを追加したので、次のオブジェクトexternalDocsを追加します。

ステップ5—`externalDocs`オブジェクトを追加する

このステップでは、externalDocsオブジェクトを追加します。このオブジェクトには、APIが持つ可能性のある他のドキュメントへのリンクが含まれています。 OpenAPIドキュメントは、APIが持つすべてのルートとそのパラメーターおよび応答を定義するだけなので、通常は参照として使用されます。各アクションを説明し、ユーザーをガイドする、人間が作成した個別のドキュメントを含めることをお勧めします。 JSONPlaceholderの場合、ガイドがあります。

仕様によると、externalDocsオブジェクトは次のようになります。

フィールド名	タイプ	説明
`description`	`string`	ターゲットドキュメントの簡単な説明。マークダウンを使用できます。
`url`	`string`	必須。ターゲットドキュメントのURL。

YAMLドキュメントに、JSONPlaceholderのガイドを指すexternalDocsオブジェクトを追加します。

externalDocs:
  description: "JSONPlaceholder's guide"
  url: https://jsonplaceholder.typicode.com/guide

Insomniaの右側にあるプレビューペインに変更が反映されていることを確認する必要があります。

これで、APIの外部ドキュメントにリンクされました。次に、serversアレイを追加します。

ステップ6—`servers`アレイを追加する

このステップでは、servers配列を追加します。この配列には、APIがホストされるURLが含まれています。作成するドキュメントは、プレースホルダーAPIとは異なるドメインでホストされます（つまり、ドキュメントはjsonplaceholder.typicode.comでホストされません）。このため、Insomniaプレビューに表示されるAPIルートの横にある Try ItOutボタンのURLを暗黙的に取得することはできません。

これを修正するために、OpenAPIはserversフィールドを提供します。 YAMLドキュメントに次の行を追加します。

servers:
- url: https://jsonplaceholder.typicode.com
  description: JSONPlaceholder

これで、APIを呼び出す方法ができました。

ステップ7—`paths`オブジェクトを追加する

このステップでは、ドキュメントの中心となるpathsオブジェクトを追加します。このオブジェクトには、APIによって提供されるすべてのルートが含まれています。また、パラメータ、メソッド、リクエスト本文、およびルートのすべての応答も含まれています。

パスオブジェクトの各キーはルート（/posts）になり、値はパスアイテムオブジェクトになります。

OpenAPI仕様によると、PathItemオブジェクトは次のようになります。

名前	タイプ	説明
`summary`	`string`	このルートのオプションの要約。
`description`	`string`	ルートが実行できることのオプションの説明。
`get` / `post` / `put` / `patch` / `delete` / etc	操作オブジェクト	このルートでの操作（メソッド）の定義。
`servers`	サーバーオブジェクトの配列	このパスのすべての操作を処理するための代替の`server`配列。
`parameters`	パラメータオブジェクトの配列	このパスのすべての操作に適用できるパラメーター。これらのパラメーターは、クエリ文字列、ヘッダー、Cookie、またはパス自体に含めることができます。

Path Itemオブジェクトにはいくつかのフィールドがあります。 summaryフィールドとdescriptionフィールドは、その名前が示すように、パスの短い要約と長い説明を提供します。 serversオブジェクトは、メインのOpenAPIドキュメントにあるものと同じです。代替サーバーを定義します。 parametersオブジェクトは、パスまたはそのパスのクエリパラメータを定義します。各Path Itemオブジェクトは、operationオブジェクトを持つことができます。 operationオブジェクトは、このAPIルートで使用できるHTTPメソッドを文書化します。

operationオブジェクトには多くのアイテムがありますが、このチュートリアルでは、より小さなセットに焦点を当てます。

名前	タイプ	説明
`tags`	`string`の配列	APIドキュメント制御用のタグのリスト。タグは、同様のルートをグループ化するために使用できます。
`summary`	`string`	操作が行うことの簡単な要約。
`description`	`string`	操作の説明。ここでマークダウンを使用できます。
`externalDocs`	外部ドキュメントオブジェクト	この操作に関する追加の外部ドキュメント。メインオブジェクトの`externalDocs`と同じです。
`parameters`	パラメータオブジェクトの配列	PathItemオブジェクトの`parameters`と同じです。
`requestBody`	ボディオブジェクトのリクエスト	リクエストの本文。メソッド`GET`または`DELETE`の場合、これは使用できません。
`responses`	応答オブジェクト	必須。この操作に対してAPIによって返される可能な応答のリスト。

tagsプロパティは、同様のパスをグループ化します。同じタグを持つパスは、1つのグループになります。 summaryおよびdescriptionフィールドは、pathオブジェクトのフィールドと同じです。それぞれ、短い要約と長い説明を追加できます。 externalDocsプロパティは、メインドキュメントのプロパティと同じです。これにより、その操作の外部ドキュメントを定義できます。

parametersオブジェクトは、pathオブジェクトのものと同じです。これにより、リクエストとともに送信する必要のあるパス、クエリ、ヘッダー、またはCookieのパラメータを定義できます。 requestBodyでは、パラメーターを定義することもできますが、リクエストの本文で定義できます。このrequestBodyフィールドは、HTTP/1.1プロトコルRFC7231で定義されているように、POST、PUT、およびPATCHリクエストでのみ使用できます。。

`/posts`ルート

次に、pathsオブジェクトにオブジェクトを作成して、APIルートを文書化します。まず、/postsルートを文書化します。 YAMLドキュメントに次の行を追加することから始めます。

paths:
  "/posts":

ノート： /posts is in quotes because it contains special symbols (/). This is required by YAML so it doesn’t misinterpret the line.

次に、キーがHTTPメソッドになり、値がPath Itemオブジェクトになるフィールドを追加する必要があります。強調表示された行を追加して、すべての投稿の配列を返すGET /postsルートを文書化します。

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts.

tagsフィールドは、同様の操作をグループ化します。（プレビューのアコーディオンがpostsと呼ばれていることに注意してください。）

次に、返される可能性のある応答を文書化します。このAPIから取得する唯一の応答は、すべての投稿の配列を含む200応答です。

JSONPlaceholderから返される投稿の例は次のようになります。

{
  "userId": 1,
  "id": 1,
  "title": "A post's title",
  "body": "The post's content"
}

これはかなり頻繁に再利用するため、この投稿用に再利用可能なコンポーネントを作成できます。これは、コンポーネントオブジェクトを使用して実行できます。 postは、componentsオブジェクト内にあるschemasオブジェクトのスキーマとして定義できます。このスキーマは、 JSONSchemaファイルのスキーマに似ています。

投稿スキーマをYAMLファイルに追加します。 componentsオブジェクトは、pathsオブジェクトではなく、ドキュメントのルートに（インデントなしで）配置する必要があることに注意してください。

components:
  schemas:
    post:
      type: object
      properties:
        id:
          type: number
          description: ID of the post
        title:
          type: string
          description: Title of the post
        body:
          type: string
          description: Body of the post
        userId:
          type: number
          description: ID of the user who created the post

上記のスキーマはobjectであり、type: objectで示されます。 propertiesには、id、title、body、userIdの4つがあります。これがスキーマの定義方法です。これで、任意のオブジェクトで$refを使用して、このスキーマを参照できます。これは、URI構文の仕様RFC3986に従って定義されています。

スキーマができたので、responsesオブジェクトを追加できます。このオブジェクトには、返されたステータスコード、または他のすべてのステータスをキャッチするためのdefaultの値を持つアイテムがあり、値は応答オブジェクトです。このオブジェクトには、応答のdescription、返されるヘッダー、応答本文、およびcontentオブジェクト。

強調表示された行をコピーして、responsesオブジェクトを/postsパスのget操作に追加します。

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts.
      <$>responses:<$>
        <$>"200":<$> # 200 Status Code
          <$>description:<$> All went well
          <$>content:<$>
            <$>application/json:<$> # Reponse is returned in JSON
              <$>schema:<$>

200は、数字ではなく文字列にするために、必ず引用符で囲んでください。

ここでは、200ステータスコードで返され、application/jsonのContent-Typeヘッダーを持つ応答を定義しています。このschemaオブジェクトでは、作成したpostスキーマへの参照を渡す必要があります。それは$refで行うことができます。

schemaの他に、application/jsonオブジェクトには任意のexamplesを含めることができます。

今のところ、schemaに投稿スキーマへの参照を追加します。

$ref: "#/components/schemas/post"

#は、ドキュメントのルートを指します。 postスキーマはcomponents/ schemas / postにあるので、このように記述します。また、#はYAMLで予約されているシンボルであるため、参照を引用符で囲む必要があります。

InsomniaDesignタブは次のようになります。

不眠症がドキュメントのプレビューをレンダリングしたことがわかります。 /postsルートは、タグのためにpostsセクションにグループ化されており、スキーマで定義したように、正しい応答も表示されます。定義したのと同じコンテンツタイプと定義した同じスキーマが右側にプレビューされます。

パスのtagやresponsesなどを変更して、リアルタイムで更新されることを確認できます。完了したら、必ず元に戻してください。

注：プレビューのパス操作で試してみるボタンを押し、次に実行ボタンを押してJSONPlaceholderAPIを呼び出して応答を受け取ります。

GETルートを文書化したら、POST /postsルートを文書化します。これは前の操作と非常に似ていますが、今回はPOSTリクエストになるため、オブジェクトのキーはpostです（以下で強調表示されています）。 YAMLファイルに次の行を追加します。

paths:
  "/posts":
    # ...
    <$>post<$>:
      tags: ["posts"]
      summary: Create a new post
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"

別の操作を定義しました。今回は、同じtagのPOSTリクエストであるため、前に定義したGETリクエストと一緒にグループ化されます。 JSONPlaceHolderによって返されるものであるため、応答にも同じスキーマがあります。

まだ1つ欠けていることがあります。それは、postメソッドもリクエスト本文を受け入れることです。まだ文書化されていないため、requestBodyオブジェクトをpost操作に追加します。リクエストの本文はresponseオブジェクトに似ています。 responseオブジェクトと同じdescriptionおよびcontentフィールドがあり、ブール値であるrequiredフィールドもあります。このフィールドは、このリクエストにボディが必要かどうかを管理します。この場合はそうなので、requestBodyオブジェクトを操作に追加します。

paths:
  "/posts":
    # ...
    <$>post<$>:
      tags: ["posts"]
      summary: Create a new post
      <$>requestBody:<$>
    <$>content:<$>
      <$>application/json:<$>
        <$>schema:<$>
          <$>$ref: "#/components/schemas/post"<$>
    <$>required: true<$>
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"

この時点で、pathsオブジェクトは次のようになります。

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
    post:
      tags: ["posts"]
      summary: Create a new post
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/post"
        required: true
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"

このセクションでは、/postsルートで使用可能なGETおよびPOST操作について説明しました。次に、/posts/:idルートを文書化します。これは、単一の投稿の読み取り、変更、または削除に使用されます。

`/posts/:id`ルート

次に、/posts/:idルートを文書化します。このルートには、GET、PUT、およびDELETEの3つの操作があります。彼らは単一の投稿を取得し、投稿を更新し、投稿を削除します。 :idは、数値にすることができる動的パラメーターです（たとえば、/posts/1、/posts/2など）。 OpenAPIでは、次の例に示すように、これは{id}として示されます。

paths:
  "/posts":
  # ...
  "/posts/{id}":
  # TODO

inプロパティは、パラメータが配置される場所を定義します。これは、query文字列、cookie、header、またはpath自体の一部にすることができます。 descriptionはパラメーターの説明です。 requiredフィールドは、パラメーターが必要かどうかを示すブール値です。 pathパラメーターの場合、パラメーターはパス自体の一部であるため、requiredはtrueである必要があります。

パスパラメータは特殊であるため、中括弧（{}）を使用してパスで定義されます。パラメータの名前は中括弧で囲まれ、nameフィールドの名前と一致する必要があります。まず、idをparameters配列のパラメータオブジェクトとして定義する必要があります。これがあなたがそれをする方法です：

paths:
  "/posts/{id}":
    parameters:
    - name: id # Must be same as the value in the {}.
      in: path
      description: ID of the post
      # Since this is in the path, the parameter HAS to be required
      required: true
      # Defining the type of the parameter
      schema:
        # In this case, it is just a string
        type: string

必ずハイフン（-）を含めてください。そうしないと、parameters配列がオブジェクトになります。

最後に文書化するのは、操作とその応答、および要求機関（ある場合）です。これは、前のセクションで行ったことと似ています。

まず、GET /posts/:id操作を追加します。これにより、単一の投稿が取得されます。

get:
  tags: ["post"]
  summary: Get a single post
  responses:
    "200":
      description: All went well
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/post"
    "404":
      description: Post not found
      content:
        application/json:
          schema:
            type: object
            properties: {}

今回は、404応答があることに注意してください。これは、投稿が見つからない場合、GETリクエストが404エラーを返す可能性があるためです。上記のコードのproperties: {}は、YAMLで空のオブジェクトを定義する方法です。

次に、投稿を更新するPUT /posts/:id操作を追加します。このメソッドは、requestBodyと404の両方の応答があるため、上記のGETメソッドとPOSTメソッドを組み合わせたものです。

put:
  tags: ["post"]
  summary: Update a post
  requestBody:
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/post"
    required: true
  responses:
    "200":
      description: All went well
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/post"
    "404":
      description: Post not found
      content:
        application/json:
          schema:
            type: object
            properties: {}

JSONPlaceholderは送信するデータを実際には検証しないため、400または422の応答はありませんが、文書化するAPIがそのようなことを行う場合（そうする必要があります）、それらの応答も必ず文書化してください。繰り返しを避けるために、前のセクションで行ったように、responsecomponentsを作成できます。

最後に、投稿を削除するDELETE /posts/:id操作を追加します。これは、404を返すため、GETメソッドと同じですが、今回の操作はdeleteです。

delete:
  tags: ["post"]
  summary: Delete a post
  responses:
    "200":
      description: All went well
      content:
        application/json:
          schema:
            type: object
            properties: {}
    "404":
      description: Post not found
      content:
        application/json:
          schema:
            type: object
            properties: {}

DELETEメソッドは、200応答であっても、空のオブジェクト（{}）のみを返すことに注意してください。

これで、JSONPlaceholderの/postsルートを正常に文書化できました。これが完全なYAMLドキュメントです。

openapi: 3.0.3

info:
  title: JSONPlaceholder
  description: Free fake API for testing and prototyping.
  version: 0.1.0

externalDocs:
  description: "JSONPlaceholder's guide"
  url: https://jsonplaceholder.typicode.com/guide

servers:
- url: https://jsonplaceholder.typicode.com
  description: JSONPlaceholder

paths:
  "/posts":
    get:
      tags: ["posts"]
      summary: Returns all posts
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
    post:
      tags: ["posts"]
      summary: Create a new post
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/post"
        required: true
      responses:
        "200":
          description: A post was created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
  "/posts/{id}":
    parameters:
    - name: id # Must be same as the value in the {}.
      # Location of the parameter.
      # Can be `path`, `cookie`, `query` or `header`
      in: path
      description: ID of the post
      # Since this is in the path, the parameter HAS to be required
      required: true
      # Defining the type of the parameter
      schema:
        # In this case, it is just a string
        type: string
    get:
      tags: ["post"]
      summary: Get a single post
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
        # But this time, you can also get a 404 response,
        # which is an empty JSON object.
        "404":
          description: Post not found
          content:
            application/json:
              schema:
                type: object
                properties: {}
    put:
      tags: ["post"]
      summary: Update a post
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/post"
        required: true
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/post"
        "404":
          description: Post not found
          content:
            application/json:
              schema:
                type: object
                properties: {}
    delete:
      tags: ["post"]
      summary: Delete a post
      responses:
        "200":
          description: All went well
          content:
            application/json:
              schema:
                type: object
                properties: {}
        # But this time, you can also get a 404 response,
        # which is an empty JSON object.
        "404":
          description: Post not found
          content:
            application/json:
              schema:
                type: object
                properties: {}

components:
  schemas:
    post:
      type: object
      properties:
        id:
          type: number
          description: ID of the post
        title:
          type: string
          description: Title of the post
        body:
          type: string
          description: Body of the post
        userId:
          type: number
          description: ID of the user who created the post

上記のドキュメントでは、JSONPlaceholderによって提供されるすべての/postsルートを文書化し、サポートされているすべてのHTTPメソッドについても説明しました。また、パラメータ、リクエスト本文、さまざまな応答についても学びました。

OpenAPIドキュメントが完成したら、次のステップはそれをユーザーが利用できるようにすることです。

ステップ8—Redocを使用してAPIドキュメントを表示する

Insomniaには見栄えの良いプレビューペインがありますが、すべてのユーザーにInsomniaがインストールされているとは限らないため、Redocを使用してOpenAPIYAMLファイルを読みやすい方法で表示します。

Redocをビルドするには、NodeJSがインストールされている必要があります。（RedocをビルドするためにNodeJSやJavaScriptを知っている必要はないことに注意してください。）

コンピューターの任意の場所に新しいフォルダーを作成します。このフォルダーにRedocをビルドし、GitHubにデプロイします。

まず、現在のOpenAPIドキュメントをこのフォルダーに保存する必要があります。現在のフォルダにopenapi.yamlという名前の新しいファイルを作成し、Insomniaの[デザイン]タブの内容をこのファイルにコピーして貼り付けます。 Redocは、このファイルを使用してAPIドキュメントを生成できるようになりました

次に、そのフォルダーでターミナルを開き、以下のコマンドを実行してRedocをビルドします。

npx redoc-cli --output index.html bundle openapi.yaml

npxは、NPM（Node Package Manager）'のCLIツールであり、CLIでインストール可能なパッケージを取得して実行します。これにより、グローバル$PATHに実際にインストールしなくても、redoc-cliを実行できます。代わりに、npxから入手できます。 redoc-cliをインストールするかどうかを尋ねられた場合は、必ずyと入力してください。次に、Redocにbundleに作成したopenapi.yamlファイルを依存関係のないHTMLファイルに指示します。この場合はindex.htmlになります。 --outputフラグ。

これにより、そのディレクトリにindex.htmlという新しいファイルが作成されます。このファイルは、Redocを利用したドキュメントです。ブラウザでファイルを開き、ファイルを調べて、定義したすべてのルートがカバーされていることを確認します。

ドキュメントサイトが生成されたので、GitHubPagesを使用して他のユーザーが利用できるようにします。

ステップ9—GitHubPagesへのデプロイ

ドキュメントのウェブサイトができたので、GitHubPagesを使用してGitHubPagesをデプロイし、世界中の人に見てもらうことができます。前提条件の一部として、新しいGitHubリポジトリを作成しました。 クイックセットアップに表示されているクローンURLをコピーします。 gitコマンドを使用して、openapi.yamlおよびindex.htmlファイルをGitHubにプッシュします。これらの2つのファイルを含むフォルダーで以下のコマンドを実行してください。

まず、gitリポジトリを初期化し、すべてのファイルをコミットします。

git init
git add .
git commit -m "First commit" # Feel free to change this message

次に、変更をGitHubにデプロイします。まず、gitに、GitHubリポジトリをリモートリポジトリにする必要があることを伝える必要があります。リモートリポジトリは通常、originという名前で保存されます。

git remote add origin YOUR_GITHUB_REPO_URL

そして最後に、次のコマンドを使用して変更をGitHubにプッシュします。

git push origin main

注： Gitはデフォルトのブランチの名前をmasterからmainに変更したため、上記のコマンドではmainが使用されます。必要に応じて、mainをmasterに置き換えてください。

GitHubを更新すると、2つのファイルが表示されます。

次に、GitHubPagesを有効にする必要があります。リポジトリの設定に移動し、サイドバーのページボタンをクリックします。ソースブランチをデフォルトのブランチ（通常はmainまたはmaster）に変更し、フォルダーを/ (root)に変更して、保存をクリックします。

最後に、https://your_username.github.io/your_repo_nameにアクセスすると、作成したRedocページが表示されます。 GitHubPagesに公開されている私のバージョンはこちらでご覧いただけます。

これにより、上記のURLで誰でもAPIを確認できるようになります。

結論

このチュートリアルでは、JSONPlaceholderAPIの/postsルートを文書化しました。パスパラメータとリクエスト本文および可能な応答を文書化しました。また、再利用可能なコンポーネントを使用して定型文を減らす方法も学びました。ソースコードとライブバージョンをお気軽にチェックしてください。

次のステップとして、JSONPlaceholderが提供する他のルート（/usersなど）を文書化するか、独自のAPIを使用してこれを試してください。 Docasaurus などのツールを使用して、ユーザーを説明およびガイドするドキュメントを追加することで、ここから先に進むことができます。 API仕様DRYを維持し、読みやすくして、将来変更できるようにしてください。 Insomniaには、APIをテストおよびデバッグする機能など、他の機能もあります。ドキュメントを読んで、それらを確認してください。

Insomniaを使用してRESTAPIのドキュメントを作成する方法

序章

前提条件

ステップ1—APIを理解する

ステップ2—不眠症プロジェクトの作成

ステップ3—OpenAPI仕様の開始

ステップ4—infoオブジェクトを追加する

ステップ5—externalDocsオブジェクトを追加する

ステップ6—serversアレイを追加する

ステップ7—pathsオブジェクトを追加する

/postsルート

/posts/:idルート