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が大きい場合に発生する可能性があります)。
方法 | ルート | 説明 |
---|---|---|
得る | /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
、それはこのチュートリアルの範囲外であるため。 The security
フィールドは、ルートの認証方法(たとえば、ユーザー名/パスワード、 JSON Web Token 、または oauth )を定義しますが、JSONPlaceholderには認証機能がありません。
ステップ4—追加 info
物体
このステップでは、ステップ1の表を使用して、Insomniaを使用したAPIのドキュメントの作成を開始します。 あなたはから始めます info
物体。
The info
オブジェクトには、文書化するAPIに関する情報が含まれています。 これには、 title
, version
APIの、APIの description
、ナレッジベースへのリンク(documentation
)、およびその利用規約(tos
).
仕様によると、これはinfoオブジェクトがどのように見えるかです。
名前 | タイプ | 説明 |
---|---|---|
title |
string |
必須。 APIのタイトル。 |
description |
string |
APIの簡単な説明。 ここでマークダウンを使用できます。 |
termsOfService |
string |
APIの利用規約へのURL。 |
contact |
連絡先オブジェクト | 公開されたAPIの連絡先情報。 |
license |
ライセンスオブジェクト | 公開されたAPIのライセンス情報。 |
version |
string |
必須。 OpenAPI仕様ではなく、ドキュメントのバージョン。 |
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
オブジェクト、前のステップの仕様に従います。
警告:YAMLはそのインデントについて非常に慎重です。 スペースでインデントする必要があり、インデントサイズはドキュメント全体で一貫している必要があります。
これで、 info
APIに関する基本情報を含むオブジェクトに、次のオブジェクトを追加します。 externalDocs
.
ステップ5—追加 externalDocs
物体
このステップでは、 externalDocs
物体。 このオブジェクトには、APIが持つ可能性のある他のドキュメントへのリンクが含まれています。 OpenAPIドキュメントは、APIが持つすべてのルートとそのパラメーターおよび応答を定義するだけなので、通常は参照として使用されます。 各アクションを説明し、ユーザーをガイドする、人間が作成した個別のドキュメントを含めることをお勧めします。 JSONPlaceholderの場合、ガイドがあります。
仕様によると、externalDocsオブジェクトは次のようになります。
フィールド名 | タイプ | 説明 |
---|---|---|
description |
string |
ターゲットドキュメントの簡単な説明。 マークダウンを使用できます。 |
url |
string |
必須。 ターゲットドキュメントのURL。 |
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オブジェクトは次のようになります。
名前 | タイプ | 説明 |
---|---|---|
summary |
string |
このルートのオプションの要約。 |
description |
string |
ルートが実行できることのオプションの説明。 |
get /post /put /patch /delete /等 |
操作オブジェクト | このルートでの操作(メソッド)の定義。 |
servers |
サーバーオブジェクトの配列 | 代替案 server このパスのすべての操作を処理する配列。 |
parameters |
パラメータオブジェクトの配列 | このパスのすべての操作に適用できるパラメーター。 これらのパラメーターは、クエリ文字列、ヘッダー、Cookie、またはパス自体に含めることができます。 |
The Path Item
オブジェクトにはいくつかのフィールドがあります。 The summary
と description
フィールドは、その名前が示すように、パスの短い要約と長い説明を提供します。 The servers
オブジェクトは、メインのOpenAPIドキュメントにあるものと同じです。 代替サーバーを定義します。 The parameters
オブジェクトは、パスまたはそのパスのクエリパラメータを定義します。 各 Path Item
オブジェクトは操作オブジェクトを持つことができます。 The operation
オブジェクトは、このAPIルートで使用できるHTTPメソッドを文書化します。
The operation
オブジェクトには多くのアイテムがありますが、このチュートリアルでは、より小さなセットに焦点を当てます。
名前 | タイプ | 説明 |
---|---|---|
tags |
の配列 string s |
APIドキュメント制御用のタグのリスト。 タグは、同様のルートをグループ化するために使用できます。 |
summary |
string |
操作が行うことの簡単な要約。 |
description |
string |
操作の説明。 ここでマークダウンを使用できます。 |
externalDocs |
外部ドキュメントオブジェクト | この操作に関する追加の外部ドキュメント。 と同じ externalDocs メインオブジェクトに。 |
parameters |
パラメータオブジェクトの配列 | と同じ parameters PathItemオブジェクト内。 |
requestBody |
ボディオブジェクトのリクエスト | リクエストの本文。 メソッドが使用できない場合、これは使用できません GET また DELETE . |
responses |
応答オブジェクト | 必須。 この操作に対してAPIによって返される可能な応答のリスト。 |
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":
注: /posts
特別な記号が含まれているため、引用符で囲まれています(/
). これはYAMLで必要とされるため、行を誤って解釈することはありません。
次に、キーが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
パスの、そしてそれがリアルタイムで更新されるのを見てください。 完了したら、必ず元に戻してください。
注:プレビューのパス操作で試してみるボタンを押し、次に実行ボタンを押して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"
別の操作を定義しました。 今回は、同じ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
注:Gitはデフォルトのブランチの名前をから変更しました master
に main
、 それで main
上記のコマンドで使用されます。 お気軽に交換してください main
と master
もし良かったら。
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をテストおよびデバッグする機能など、他の機能もあります。ドキュメントを読んで、それらを確認してください。