Swaggerは、SpecファイルをJSONデータにエクスポートすることができます。SpecファイルをJSONにエクスポートすると、他のツールとのインテグレーションが簡単に実現されることが可能です。しかし、より綺麗で読みやすいAPIドキュメントを作るために、SwaggerのSpecファイルをHTMLやMarkdownなどのフォーマットにエスクポートする必要があります。それでは、どうやってSwaggerのファイルをHTMLやMarkdownにエクスポートすれば良いのですか？次は、この方法について皆さんに紹介します。
SwaggerのデータをHTMLやMarkdownなどのフォーマットにエクスポートしたい場合は、Apidogという便利なAPI管理ツールを利用する必要があります。SwaggerのJSONデータをApidogにインポートすれば、それを簡単にHTMLやMarkdownフォーマットに再エクスポートできます。完全無料で使えるApidogを下記のボタンから取得しましょう👇👇👇
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キュメントも生成することができるので、非常に便利です。
