OpenAPI(Swagger)仕様書をHTMLに出力

OpenAPI仕様書をHTMLに出力すると、API仕様を簡単に確認することもできますし、他人に共有することも簡単になります。本文では、非常に使いやすいAPI管理ツールを使って、OpenAPIの仕様書をHTMLに簡単に出力する操作手順を皆さんに紹介します。

中村 拓也

中村 拓也

11 5月 2025

OpenAPI(Swagger)仕様書をHTMLに出力

OpenAPI(Swagger)仕様書を作成するには、yamlかJSONを使用するのは一般的です。ただし、yamlとJSONファイルはコードベースのファイルで内容を直感的に表示できないんですし、他の人に共有することも難しくなっています。このような場合は、OpenAPI仕様書をHTMLに出力すると、これらのデメリットを大抵解決できます。本文では、非常に使いやすいAPI管理ツールを使って、OpenAPIの仕様書をHTMLに簡単に出力する操作手順を皆さんに紹介します。

button

OpenAPI(Swagger)仕様書とは

OpenAPI(Swagger)仕様書は、APIの設計書を記述するための仕様形式として、一般的にJSONやYAML形式でAPIの仕様を記述しています。だから、開発者は大抵JSONやYAML形式の仕様書を理解することができますが、これらの仕様書を一般のユーザーに共有すると、彼らは、それを読み解くことができない可能性があります。

OpenAPI仕様書の可視化

実際には、OpenAPI(Swagger)が提供してくれる標準ツールのSwagger UIなどを使って、コードベースのJSONやYAML形式の仕様書の可視化を実現することができます。例えば、次の操作手順を参照して、OpenAPI(Swagger)仕様書を直感的なUIで表示することができます。

ステップ⒈Node.jsをインストールします。

ターミナルでプロジェクトフォルダに移動し、次のコマンドを実行してswagger-uiをインストールします。

npm install swagger-ui-dist --save

ステップ⒉プロジェクトのルートにOpenAPI仕様書のswagger.jsonかswagger.yamlファイルを作成し、APIの定義を記述します。

ステップ⒊そして、index.htmlファイルを作成し、次のコードを記述します。ここでSwaggerUIBundleの下のurlで、OpenAPI仕様書のディレクトリ情報を記入する必要があります。

<!DOCTYPE html>
<html>
  <head>
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="./node_modules/swagger-ui-dist/swagger-ui.css">
  </head>
  <body>
    <div id="swagger-ui"></div>

    <script src="./node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
    <script>
      const ui = SwaggerUIBundle({
        url: "./swagger.json",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    </script>
  </body>
</html>

ステップ⒋ブラウザでindex.htmlを開くと、Swagger UIが呼び出され、SwaggerUIBundleの下のurlで定義されたAPI仕様書が表示されます。

Swagger UIの仕様書のイメージ

なぜOpenAPI仕様書をHTMLに出力?

Swagger UIなどのツールを使って、OpenAPI(Swagger)仕様書の可視化を実現する方法はそんなに難しくないんですが、誰でも操作できるわけでもありません。そこで、OpenAPI(Swagger)仕様書をHTMLに変換すると、一般ユーザーにとってより分かりやすくなるなど、多くのメリットがあります。

API仕様書をHTMLで出力する主なメリットは以下の通りです:

確かに、HTML形式のAPI仕様書が開発者にとって理解しやすく、メンテナンス性や拡張性に優れていることが大きなメリットです。HTMLの特徴を生かした柔軟なドキュメント作成が可能となります。

OpenAPI(Swagger)仕様書をHTMLに出力する方法

それでは、yamlかJSONデータで定義されているOpenAPI仕様書をどうやってHTML形式に出力すれば良いのでしょうか?次は、非常に使いやすいAPI管理ツールを使って、それを実現する方法を皆さんに紹介します。

button

Apidogは、包括的なAPI管理ツールとして、OpenAPI、Postmanなどの仕様にも完璧に互換できるため、yamlかJSON形式の仕様書を直接にApidogにインポートして、それをHTMLに出力することができます。

ApidogでOpenAPI仕様書を1クリックでHTMLに出力

ステップ⒈プロジェクトの設定を開き、「データをインポート」をクリックすると、「OpenAPI/Swagger」を選択して、YAMLファイルをApidogにドラッグします。

YAMLをApidogにインポート

ステップ⒉ここでYAMLファイルが解析され、データの保存先を選択すると、「確認」ボタンをクリックするだけで、それを簡単にApidogにインポートできます。

YAMLの保存先を選択してインポート

ステップ⒊APIをインポートすると、ApidogでそのAPIを右クリックして「エクスポート」を選択します。

APIのエクスポート

ステップ⒋エクスポートの形式を「HTML形式」に指定して、「エクスポート」をクリックします。

仕様書をHTML形式にエクスポート

ここで、HTMLファイルがエクスポートされます。任意のブラウザを使って、このHTMLファイルを開くと、非常に直感的なAPI仕様書が表示されます。

このHTMLファイルを他の人に共有する場合、他の人も簡単にこのHTMLファイルを開くことで、APIの仕様がわかるようになると思います。

button

Explore more

MindsDB: あらゆるITユーザーのための万能MCPサーバー

MindsDB: あらゆるITユーザーのための万能MCPサーバー

MindsDBは、200以上のデータソースへの接続を容易にし、AIアプリの構築やインサイトの探索をプロのように実現します。さらなるデータソースの接続や、APIdogでのAPIドキュメント化をお試しください。

26 5月 2025

IT初心者必見!Google Drive MCPサーバーでAIを強化する方法

IT初心者必見!Google Drive MCPサーバーでAIを強化する方法

MCPサーバーは、AIをソフトウェア開発でより効果的なパートナーにし、生産性を向上させます。Google Drive MCPサーバーはAIのデータ統合を簡素化し、API開発ではApidog MCPサーバーが重要な役割を果たします。

22 5月 2025

2025最新:Node.jsでWebSocketを利用する

2025最新:Node.jsでWebSocketを利用する

WebSocketはブラウザとサーバー間のリアルタイムな双方向通信を可能にする技術です。Node.jsでwsモジュールを使って、WebSocket通信を簡単に実現することができます。本文では、Node.jsでWebSocketを利用する方法を紹介します。必要な方はぜひこの記事の内容を参照してください。

12 5月 2025

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる