はじめに
インターンや勉強会で、フロントエンドの開発とバックエンドの開発が連携するためにSwaggerというものを使うと聞きました。今までは個人開発をしてきたので使用する機会がありませんでしたが、今後使う機会はあるかと思うので、どのようなものか調べてみました。
Swaggerとは
Swaggerとは、REST API を定義するためのオープン仕様です。もっとざっくりいうと、「API仕様書を記述するための便利ツール」であるようです。
API仕様書とは
API仕様書とは、そのAPIの目的や種類、リクエストやレスポンスの形式などが記載されたドキュメントです。基本的には、APIの種類、認証形式、エンドポイント、パラメータなどの情報を記載します。
API仕様書の例
API仕様書がどのようなものかよく分からなかったため、chatGPTに書いてもらいました。この例をもとに解説します。誤った点があったらすいません。
エンドポイント：`POST/ api/users
概要：新しいユーザーを作成します。
メソッド：POST
リクエスト例：
POST /api/users
Content-Type: application/json
Authorization: Bearer <token>
- リクエストボディ：
{
"name": "John Doe",
"email": "john.doe@example.com",
"password": "securepassword123"
}
レスポンス例：
- 成功(201 Created)：
{
"id": 123,
"name": "John Doe",
"email": "john.doe@example.com",
"created_at": "2024-10-11T10:00:00Z"
}
- エラー(400 Bad Request)：
{
"error": "Invalid email address"
}
認証：必須 (Bearer Token)
ステータスコード：
- 201 Created: 成功時
- 400 Bad Request: 入力が不正
- 401 Unauthorized: 認証に失敗
制限：1分あたり100リクエストまで
API仕様書に含まれる主な項目
エンドポイントのURL
APIの各機能にアクセスするためのURLを記載します。
HTTPメソッド
GET、POSTといったメソッドを記述します。
リクエストパラメータ
APIに送信するデータ（クエリパラメータやボディパラメータ）を定義します。
レスポンスフォーマット
APIから返されるデータの形式や構造を記述します。
ステータスコード
成功やエラーの際に返されるコードを定義します。
認証・認可
APIへのアクセスが制限されている場合、認証方法やアクセス制御に関する説明を含めます。
エラーメッセージ
失敗したリクエストに対して返されるエラーメッセージの内容を定義します。
制限
APIの呼び出し回数の制限や頻度について記述します。