APIの仕様をチームメンバーに共有したり、APIの使い方をユーザーにわかりやすく解説したりするために、APIドキュメントを作成する必要があります。Swagger（OpenAPI）は、APIの標準仕様として、一番多くの場合は、Swagger APIドキュメントを作成する必要があるのでしょう。本文では、SwaggerのAPIドキュメントを作成する方法を詳しく皆さんに紹介します。
また、SwaggerやOpenAPI仕様にも完璧に対応可能なApidogを使用して、次のようなより綺麗なAPIドキュメントを生成する方法も一緒に紹介するので、必要な方はご参照ください。
Swagger（OpenAPI）とは
Swagger(OpenAPI)とは、APIの仕様を記述するためのフレームワークです。SwaggerはもともとはSmartBear Softwareによって作成されたオープンソースの仕様だったのですが、後にOpenAPI Initiativeによってオープン標準仕様「OpenAPI Specification」として管理されるようになりました。
現在ではSwaggerとOpenAPIは同義語のように使われることが多く、APIの仕様記述やドキュメント生成に広く利用されています。REST APIの設計を行う際にはほぼ必須のツールと言えるでしょう。
shimizu chioka
Swagger APIドキュメントはどのようなもの？
Swagger APIドキュメントとは、Swagger/OpenAPIの仕様ファイルをもとに生成される、APIの仕様書のようなドキュメントのことを指します。
Swaggerでは、APIのエンドポイント、リクエストやレスポンスのデータ構造、認証方法、使用できるHTTPメソッドなどの仕様をJSONやYAMLで記述します。
この仕様ファイルから、Swaggerのツールやライブラリを使ってHTMLやPDFなどのドキュメントが自動生成できます。
Swagger APIドキュメントの主な特徴:
- APIのエンドポイント一覧が確認できる
- 各エンドポイントのリクエスト・レスポンス図が含まれる
- パラメータやデータ構造が記載されている
- 実行可能なAPI例が含まれ、ライブでテストできる
- ドキュメントとコードが一貫した状態に保たれる
このように、Swagger APIドキュメントを作成することで、開発者がAPIを使いやすく、ドキュメントと実装を同期しやすくなります。API開発時にはほぼ必須のドキュメントと言えます。
操作ガイド：Swagger APIドキュメントを作成する
上記の内容から、Swagger及びそのAPIドキュメントの概要を知った上、次の操作ガイドを参照して、Swagger Hubというツールを使って、SwaggerのAPIドキュメントを簡単に作成することができます。
ステップ⒈ Swagger Hubというツールを開き、左側のメニューから「＋Create New」をクリックします。
ステップ⒉必要な情報（所有者、プロジェクト、仕様など）を記入して、「Create API」をクリックします。
Specification：OpenAPI仕様のバージョンを指定します。
Template：APIドキュメントのテンプレートを指定します。ここで空のドキュメンテーションを作成することもできますし、Swaggerが提供してくれるテンプレートを選択することができます。
ステップ⒊ここでSwagger APIドキュメンテーションのページが表示されます。APIを新規作成する場合は、コードとドキュメンテーションのサンプルが表示されます。ここで、左側のパネルで、APIのデータを編集して、右側のドキュメンテーションはそれに伴って変更します。
Apidogでより綺麗なAPIドキュメントを生成
以上でSwaggerのAPIドキュメントを作成する方法を紹介しました。Swagger APIドキュメントは、そんなに直感的で読みやすいとは言えません。
ここで、より使いやすいAPI管理ツールのApidogを使って、より綺麗なAPIドキュメントを生成する方法を紹介したいと思います。Apidogは、APIの設計とドキュメント生成・共有に長けているだけではなく、APIのテスト、テストの自動化及びAPIモック機能も非常に強力的です。Apidogというツールを利用すると、APIの設計から公開までの各段階においても効果を発揮できると言えます。
ApidogはSwagger（OpenAPI）の仕様に完璧に互換できるので、JSONやYAMLフォーマットのOpenAPI 3、Swagger 1、2、3のAPIを直接にApidogにインポートできます。
ステップ⒈プロジェクトの設定を開き、「データをインポート」をクリックすると、「OpenAPI/Swagger」を選択して、SwaggerのファイルをApidogにドラッグします。
ステップ⒉ここでSwagger仕様のファイルが解析され、データの保存先を選択すると、「確認」ボタンをクリックするだけで、それを簡単にApidogにインポートできます。
そして、ApidogというAPI管理ツールを使って、当該APIをテストしたりすることができるようになりますし、APIリクエストを送信して直ちに内蔵のモックサーバーを使って仮のレスポンスデータを取得することもできます。
ステップ⒊インポートしたAPIのデータに基づいて綺麗なAPIドキュメントを生成するには、左側メニューから「共有」をクリックして、Apidogの共有機能を利用して、非常に読みやすいAPIドキュメントを生成できます。
上記のように、共有項目を追加すると、「開く」をクリックして、APIドキュメントを開くことができます。「コピー」をクリックして、このAPIドキュメントのリンクをコピーして、他のチームメンバーに共有することができます。
ご案内：共有設定を行うことで、共有するAPIドキュメントを選択することもできますし、プライバシーを保護するためにセキュリティ設定を行うことも可能です。
まとめ
Swagger/OpenAPIを利用してAPIの設計を行う場合、生成されるデフォルトのAPIドキュメントでは直感的ではない場合があります。このような場合、Apidogというツールを利用することで、Swagger/OpenAPIの仕様ファイルからより洗練されたAPIドキュメントを生成できます。
Apidogには、Swagger/OpenAPIファイルのインポート機能があり、そのままAPIのデータを取り込むことができます。取り込んだAPIのデータをもとに、Apidogの強力なドキュメント生成機能を使って、読みやすく、分かりやすいAPIリファレンスを作成できます。
また、ApidogにはAPIのテストやモック機能もあるため、ドキュメントの生成だけでなく、APIの開発全体を支援してくれる優れたツールといえます。Swagger/OpenAPIでAPI設計を行う際は、ぜひApidogも組み合わせることで、より高品質なAPIドキュメントの作成と、効率的なAPI開発が実現できるでしょう。
