この記事では、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開発の透明性と効率が向上します。