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

序章

このチュートリアルでは、 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が大きい場合に発生する可能性があります）。

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

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

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

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

次のスクリーンショットに示すように、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仕様のバージョンを指定します。

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

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

ステップ4—追加 info 物体

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

The info オブジェクトには、文書化するAPIに関する情報が含まれています。 これには、 title, version APIの、APIの description、ナレッジベースへのリンク（documentation）、およびその利用規約（tos).

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

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

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

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

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

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

ステップ5—追加 externalDocs 物体

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

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

YAMLドキュメントに、 externalDocs JSONPlaceholderのガイドを指すオブジェクト：

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）、値は PathItemオブジェクトになります。

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

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

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

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

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

The /posts ルート

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

paths:
  "/posts":

次に、キーがHTTPメソッドになり、値が Path Item 物体。 文書化する GET /posts 強調表示された行を追加することにより、すべての投稿の配列を返すroute：

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

The tags フィールドは、同様の操作をグループ化します。 （プレビューのアコーディオンがどのように呼び出されるかに注意してください posts.)

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

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

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

これはかなり頻繁に再利用するため、この投稿用に再利用可能なコンポーネントを作成できます。 これは、コンポーネントオブジェクトを使用して実行できます。 あなたは定義することができます post のスキーマとして schemas オブジェクト、内部になります components 物体。 このスキーマは、 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. それは4つあります properties: id, title, body、 と userId. これがスキーマの定義方法です。 今、あなたは使用することができます $ref このスキーマを参照する任意のオブジェクト。 これは、URI構文の仕様RFC3986に従って定義されています。

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

追加します responses に反対する get の操作 /posts 強調表示された行をコピーすることによるパス：

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 ステータスコード、および Content-Type のヘッダー application/json. これで schema オブジェクト、あなたはへの参照を渡す必要があります post 作成したスキーマ。 それはで行うことができます $ref.

以外に schema、 application/json オブジェクトには、 examples あなたが与えたい。

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

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

# ドキュメントのルートを指します。 以来 post スキーマはにあります components/schemas/post、それはあなたがそれを書くべき方法です。 それ以来 # はYAMLで予約されているシンボルであるため、refを引用符で囲む必要があります。

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

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

次のような何かを変更してみることができます tag または responses パスの、そしてそれがリアルタイムで更新されるのを見てください。 完了したら、必ず元に戻してください。

とともに 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"

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

まだ足りないものが1つあります。 post メソッドはリクエスト本文も受け入れます。 まだ文書化されていないので、 requestBody に反対する post 手術。 リクエストの本文は、 response 物体。 あります description と content フィールド、これは response オブジェクト、そしてまたあります 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"

このセクションでは、 GET と POST で利用可能な操作 /posts ルート。 次に、ドキュメントを作成します /posts/:id ルート。単一の投稿の読み取り、変更、または削除に使用されます。

The /posts/:id ルート

次に、ドキュメントを作成します /posts/:id ルート。 このルートには3つの操作があります。 GET, PUT、 と DELETE. 彼らは単一の投稿を取得し、投稿を更新し、投稿を削除します。 :id は数値にすることができる動的パラメータです（例： /posts/1, /posts/2など）。 OpenAPIでは、これは次のように表されます。 {id}、次の例に示すように：

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

The in プロパティは、パラメータが配置される場所を定義します。 これは query 文字列、 cookie、 の中に header、またはの一部として path 自体。 The description パラメータの説明です。 The 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エラーを返す可能性があるためです。 The properties: {} 上記のコードでは、YAMLで空のオブジェクトを定義する方法を示しています。

次に、 PUT /posts/:id 投稿を更新する操作。 このメソッドは、上記のGETメソッドとPOSTメソッドの両方を備えているため、これらを組み合わせたものです。 requestBody と 404 応答。

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がそのようなことを行う場合（そうすべきです）、それらの応答も必ず文書化してください。 繰り返さないように、作成することができます response components、前のセクションで行ったように。

そして最後に、 DELETE /posts/:id 投稿を削除する操作。 これはGETメソッドと同じです。これは、 404、しかし今回は操作は 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 応答。

そしてそれで、あなたは首尾よく文書化しました /posts JSONPlaceholderのルート。 これが完全な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

上記のドキュメントでは、すべてをドキュメント化しています /posts JSONPlaceholderによって提供されるルート。また、サポートされているすべての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 は、CLIでインストール可能なパッケージをフェッチして実行するためのNPM（Node Package Manager）のCLIツールです。 これにより、実行できます redoc-cli 実際にグローバルにインストールせずに $PATH. 代わりに、 npx. 必ず入力してください y インストールを求められた場合 redoc-cli か否か。 次に、Redocに次のように指示します bundle the 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

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

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

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

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

結論

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

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