ガイド：SwaggerをJSON/ HTML/ Markdownフォーマットにエクスポート

Swaggerは、SpecファイルをJSONデータにエクスポートすることができます。SpecファイルをJSONにエクスポートすると、他のツールとのインテグレーションが簡単に実現されることが可能です。しかし、より綺麗で読みやすいAPIドキュメントを作るために、SwaggerのSpecファイルをHTMLやMarkdownなどのフォーマットにエスクポートする必要があります。それでは、どうやってSwaggerのファイルをHTMLやMarkdownにエクスポートすれば良いのですか？次は、この方法について皆さんに紹介します。

Swaggerとは

Swaggerは、一般的な意味が以下のように、2つあります。

• SmartBear SoftwareのAPI開発者向けのツールスイートです。
• OpenAPI仕様の基礎となっている以前の仕様で、Swagger仕様とも言えます。

Swaggerツール

Swagger（またはOpenAPI）のツールは、APIの設計、ドキュメント化、テスト、モック作成、コード生成など、さまざまな目的で使用されます。以下にいくつかの一般的なSwaggerツールを挙げます。

• Swagger Editor: Swaggerの仕様書を編集し、即座にプレビューできるオンラインエディタです。
• Swagger UI: Swaggerの仕様書をユーザーフレンドリーなHTMLドキュメントとして表示するためのツールです。
• Swagger Codegen: Swaggerの仕様書からクライアントコードやサーバーのスタブを生成するツールです。
• Swagger Inspector: APIのテストとデバッグを支援するためのツールです。リクエストを作成し、レスポンスを確認することができます。
• SwaggerHub: Swaggerの仕様書を管理、共有、ホストするためのプラットフォームです。チームでの共同作業やバージョン管理に便利です。

つまり、Swaggerのツールスイートを使って、Swagger仕様書や定義書を作成したり、編集したり、閲覧したりすることができるということです。

Swagger仕様

SwaggerとOpenAPIはAPIの定義とドキュメント化のためのフレームワークです。Swaggerは最初にSmartBear Softwareによって作成されたOSSのフレームワークで、APIの定義やインタラクティブなドキュメントを自動生成できます。OpenAPIはSwagger 2.0仕様をベースにした業界標準の仕様です。

最近のバージョンとしてはOpenAPI 3.0があり、JSON/YAMLファイルでAPIを定義できるほか、豊富な機能が追加されています。多くの場合このOpenAPI 3.0仕様に準拠したSwaggerツールを利用するのが一般的です。

SwaggerのSpecファイルをJSONにエクスポート

それでは、どうやってSwaggerのSpecファイルをJSONにエクスポートすることができますか？

Swaggerのオフィシャルサイトで提供されているSwagger Petstoreというオープンソースのプロジェクトを例にして、SpecファイルをJSONデータとしてエクスポートする方法を紹介します。

ステップ⒈上記のリンクをクリックして、Swagger Petsotreプロジェクトのページにアクセスします。このページにアクセスすると、プロジェクト名の下に表示されるURLをクリックします。

ステップ⒉ここでブラウザでJSONデータの中身が表示されます。このページで右クリックして、「別名で保存」を選択して、このJSONデータをパソコンに保存することができます。

SwaggerのSpecファイルをHTMLやMarkdownにエクスポート

上記のステップを参照して、SwaggerのSpecファイルを簡単にJSONデータとしてエクスポートできます。しかし、Swaggerのツールを使って、SpecファイルをHTMLやMarkdownファイルにエクスポートすることができません。

それでは、より分かりやすいAPIドキュメントを作るために、どうやってSpecファイルをHTMLかMarkdownファイルにエクスポートすれば良いのでしょうか？ここでApidogという便利なAPI管理ツールを利用する必要があります。Apidogは、APIの設計、ドキュメンテーション、テスト、モックサーバーにも対応可能なAPI管理ツールとして、SwaggerやOpenAPI仕様に完璧に互換できます。

SwaggerのJSONデータをApidogにインポートすれば、それを簡単にHTMLやMarkdownフォーマットに再エクスポートできます。

JSONデータをApidogにインポート

Apidogは、SwaggerやOpenAPI仕様のJSONデータに完璧に互換できますので、Apidogを開き、プロジェクトで「設定」→「データのインポート」の順にクリックすると、「OpenAPI/Swagger」を選択して、JSONデータを簡単にApidogにインポートできます。

JSONデータをインポートすると、すべてのエンドポイント、パラメータ、フィールドなどのデータが解析され、Apidogで利用することができます。

HTMLかMarkdownファイルにエクスポート

そして、Apidogという包括的なAPI管理ツールを使って、SwaggerのSpecファイルをHTMLかMarkdownファイルにエクスポートすることが可能です。

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

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

ここで、HTMLファイルかMarkdownファイルがエクスポートされます。これらのファイルを他の人に共有する場合、他の人も簡単にHTMLファイルやMarkdownファイルを開くことで、APIの仕様がわかりやすくなると思います。

まとめ

Swaggerでは、Specファイルを簡単にJSONデータとしてエクスポートすることができますが、HTMLかMarkdownフォーマットのデータとしてエクスポートすることができません。APIドキュメント作成などの原因で、SwaggerのSpecファイルをHTMLやMarkdownなどのデータとしてエクスポートする必要がある場合、SwaggerからJSONデータを取得し、それをApidogにインポートする必要があります。

Apidogは、インポートしてきたJSONデータを簡単にHTMLやMarkdownファイルとしてエクスポートすることが可能なので、非常に役立つツールだと思います。また、ApidogはSwaggerのSpecファイルに基づいて、1クリックで綺麗で読みやすいAPIキュメントも生成することができるので、非常に便利です。