API仕様書作成・OpenAPI生成
API基本情報・Endpoint・Parameter・Request/Responseを入力すると、同じ内容からAPI仕様書PDF・OpenAPI YAML・OpenAPI JSONを生成できます。
エンドポイント(0/50)
エンドポイントがまだ登録されていません。「+ エンドポイントを追加」から追加してください。
プレビュー
「プレビュー生成」を押すと、現在の入力内容から作成される仕様のプレビューを確認できます。
出力
このツールでできること
API仕様書・OpenAPI出力のための主な機能です。
- API基本情報(API名・概要・Version・Base URL・認証方式)とEndpoint(Method・Path・Parameters・Request Body・Responses)を入力すると、同じ入力からAPI仕様書PDF・OpenAPI YAML・OpenAPI JSONをまとめて生成できます
- 認証方式は「なし」「Bearer Token」「API Key(header/query)」に対応し、OpenAPIのsecuritySchemes/securityへ反映します
- PDF出力はブラウザの印刷機能を使って行います(印刷画面から「PDFとして保存」を選択します)
- 入力内容はブラウザ内で処理され、サーバーへ送信・保存されません
手順を見る
- 「サンプル入力」で例を読み込むか、API名・API概要・Version・Base URL・認証を入力します
- 「+ エンドポイントを追加」でエンドポイントを追加し、Parameters・Request Body・Responsesを入力します
- 「プレビュー生成」で内容を確認します
- 「PDF出力」「OpenAPI YAMLダウンロード」「OpenAPI JSONダウンロード」から、必要な形式で出力します
API仕様書作成・OpenAPI生成の仕組みと注意点
このツールの動作の仕組みと、利用時の注意点を説明します。
詳しい仕様を見る
対応しているOpenAPIバージョンと範囲
生成するOpenAPI文書は3.1.0のサブセットです。API基本情報(info)・Base URL(servers。1件のみ)・Endpoint(paths)・Parameters・Request/Response・認証設定(security)を出力しますが、components/schemas・$ref・tags・operationId・複数のserversは生成しません。Endpointは最大50件まで登録できます。
Request/Response BodyはExampleのみを出力します
入力したJSON Exampleは、そのままexampleとしてOpenAPIへ出力されます。Exampleから型や必須項目を推測してschemaを自動生成することは行いません(ParameterのTypeとは扱いが異なります)。
認証方式の対応範囲
対応する認証方式は「なし」「Bearer Token」「API Key(header/query)」の3種類です。API KeyのLocationはheaderまたはqueryのみを選択でき、cookieは選択できません。OAuth2・OpenID Connectには対応していません。
PDF出力はブラウザの印刷機能を使用します
「PDF出力」は印刷用レイアウトを表示し、ブラウザの印刷ダイアログを開く方式です。印刷画面で「PDFとして保存」を選択して保存します。ボタン操作だけで.pdfファイルが自動的にダウンロードされるわけではありません。
PDF・YAML・JSONの使い分け
OpenAPI YAMLとOpenAPI JSONは、同じ入力内容から生成される同一のデータを異なる表現形式で書き出したものであり、内容に違いはありません。利用先のツールが読み込める形式を選んでください。一方、PDFは人が読むための仕様書としてのレイアウトで出力するものであり、Swagger UI等の機械可読なOpenAPIツールへ読み込む用途にはYAML・JSONを使用してください。
よくある質問
生成したOpenAPIはOpenAPI 3.1として問題なく使えますか?
本ツールはOpenAPI 3.1.0形式で出力しますが、対応範囲はcomponents/schemas・$ref・tags・operationId・複数serverを含まないサブセットです。生成後は、実際に利用するSwagger UI等のOpenAPIツールへ読み込んで内容を確認することをおすすめします。
PDFはボタンを押すと自動でダウンロードされますか?
いいえ。ブラウザの印刷ダイアログが開き、「PDFとして保存」を選択して保存する方式です。
Request/Response BodyのJSON SchemaはOpenAPIに含まれますか?
含まれません。入力したJSON Exampleをそのままexampleとして出力し、Schemaの自動推測・生成は行いません。
OAuth2やAPI Keyのcookie指定には対応していますか?
対応していません。対応する認証方式は「なし」「Bearer Token」「API Key(header/query)」の3種類のみです。
YAMLとJSONのどちらを使えばよいですか?
生成されるOpenAPIの内容はYAML・JSONで同一です。利用先のツールやチームの慣習に合わせて、読み込みやすい形式を選んでください。
入力した内容は保存されますか?
いいえ。ブラウザ内で処理され、サーバーへの送信やLocalStorage等への保存は行いません。ページを離れる・再読み込みすると入力内容は消えます。