この記事では、Visual Studio Code（VSCode）を使用してOpenAPI v3のYAMLファイルをHTMLドキュメントに変換するプロセスを詳しく説明します。例として、OpenAPIの公式GitHubリポジトリにあるPetstore APIのYAMLファイルを用いて手順を示します。
VSCodeのプラグイン「OpenAPI (Swagger) Editor」のインストール
- VSCodeを開き、拡張機能タブから「OpenAPI (Swagger) Editor」を検索してインストールします。これによりYAMLファイルの編集が容易になります。
YAMLファイルのダウンロード
この記事では例として、Petstore APIのYAMLファイルを使用します。以下の手順でファイルをダウンロードしてください：
- リンクをクリックしてファイルページにアクセスし、「Raw」ボタンをクリック後、右クリックして「名前をつけてリンク先を保存...」を選択し、ファイルをローカル環境に保存します。
プレビュー
方法1: VSCode内でのプレビュー
- VSCodeでダウンロードしたYAMLファイルを開きます。
- 「OpenAPI (Swagger) Editor」拡張機能により、右上に表示される「Preview」ボタンをクリックすると、サイドパネルにHTMLプレビューが表示されます。
方法2: コマンドラインを使用した変換
必要なツールとプラグインの準備
1. Node.jsとnpmのインストール
Redocly OpenAPI CLIを使用する前に、Node.jsとnpm（Node.jsのパッケージマネージャ）がインストールされている必要があります。最新バージョンのNode.jsをインストールすると、npmも一緒にインストールされます。
-
Node.jsの公式サイト からインストーラをダウンロードし、指示に従ってインストールしてください。このプロセスにより、
nodeとnpmコマンドが利用可能になります。
2. Redocly OpenAPI CLIのインストール
- ターミナルまたはコマンドプロンプトを開き、以下のコマンドを実行してRedocly OpenAPI CLIをインストールします：
npm install -g @redocly/cli- このコマンドはグローバルにCLIツールをインストールします。
- 保存したYAMLファイルがあるディレクトリにコマンドラインで移動します。
- 以下のコマンドを実行してHTMLファイルを生成して、プレビューサーバーを起動します。
openapi preview-docs petstore.yaml - ブラウザで、http://127.0.0.1:8080 を開きプレビューを確認します。
- Ctrl + C で停止します。
HTMLファイル出力
OpenAPI (Swagger) Editor を使用して直接 HTML ファイルを生成する機能は、標準の機能としては提供されていません。しかし、OpenAPI (Swagger) Editor で API ドキュメントを作成・編集した後、別のツールを使って HTML ドキュメントに変換することは一般的なアプローチです。以下はその方法をいくつか紹介します。
@redocly/cli を使用して HTML ドキュメントを生成する
@redocly/cli は Node.js がインストールされている必要があります。まだインストールされていない場合は、Node.js の公式サイトからダウンロードしてインストールしてください。
-
Node.js をインストールします。
-
コマンドラインを開いて、以下のコマンドを実行し、@redocly/cli をインストールします
npm install -g @redocly/cli -
HTML ドキュメントの生成
npx @redocly/cli build-docs <path-to-your-openapi-file.yaml> --output <output-directory>例えば、petstore.yaml というファイルから HTML を生成し、現在のディレクトリに出力する場合は以下のようになります（環境によって、数秒かかります）
npx @redocly/cli build-docs petstore.yaml --output ./petstore.htmlこれにより、
petstore.yamlからpetstore.htmlという HTML ドキュメントが作成されます。
3. Swagger Codegen を使用する
Swagger Codegen を使用しても、OpenAPI スペックから HTML ドキュメントを生成することが可能です。Java 環境が必要ですが、コマンドラインから HTML ドキュメントを生成することができます。使用方法は以下の通りです：
-
Swagger Codegen をダウンロードし、適切に設定します。
-
以下のコマンドを使用して HTML ドキュメントを生成します：
java -jar swagger-codegen-cli.jar generate -i your-openapi-file.yaml -l htmlこのコマンドは、
your-openapi-file.yamlから HTML ドキュメントを生成します。
これらの方法を利用することで、OpenAPI Editor で作成したスペックから HTML ドキュメントを生成することが可能です。各ツールの設定やインストール方法については、それぞれの公式ドキュメントを参照してください。
まとめ
VSCodeのプラグイン「OpenAPI (Swagger) Editor」やRedocly OpenAPI CLIを使用することで、APIドキュメントの作成と管理が容易になります。これにより、API開発の透明性と効率が向上します。