概要
API開発を初めて、仕様書を作成するにあたって、API Blue printを使おうと思ったが、
Swaggerが主流のようなので初めて使ってメモを残す。
Swaggerとは
Swaggerは**OpenAPI仕様(旧名Swagger仕様)**に基づいて構築された一連のオープンソースツールであり、REST APIの設計、構築、文書化、および使用に役立つ。
OpenAPI仕様 => REST API を定義するための業界標準
主なSwaggerツール
| ツール名 | 説明 |
|---|---|
| Swagger Editor | ブラウザでオンラインでAPI仕様を記述できる ※オフラインでもできます |
| Swagger UI | OpenAPI仕様をAPIドキュメントとしてレンダリングする為のツール |
Swaggerのいいところ
- Swagger UIを使用してAPIドキュメントを生成すると、ユーザーは**ブラウザでAPI呼び出しを直接試すことができる**
導入手順(ローカルでやる場合)
1.SwaggerEditorをcloneする
$ git clone https://github.com/swagger-api/swagger-editor.git
2.SwagerEditor起動
$ open swagger-editor/index.html
これでブラウザが起動します！
あとはヘッダーからFile > Clear Editorでマッサラにして仕様書を作成するだけ。
仕様
- 商品情報を管理しているproductsテーブルへのAPI操作
※今回はたださわってみただけの記事なので、テーブル構造は鬼シンプルに、またHTTPリクエストも下記1ずつにします。
HTTPリクエスト
| リクエスト名 | path | 機能 |
|---|---|---|
| GET | api/ |
全件取得 |
| POST | api/ |
1件登録 |
| PUT | api/{id} |
対象の1件のレコードの内容の更新 |
| DELET | api/{id} |
対象の1件のレコードを削除 |
テーブル定義
products
| カラム名 | データ型 | Key |
|---|---|---|
| id | int | PK |
| name | varchar(255) |
完成したymlファイル
コメントアウトで説明が書かれているのでご覧ください。
# swaggerのバージョン定義
swagger: "2.0"
# APIについての情報を書く
info:
# API名
title: "商品情報API"
# APIのバージョン
version: "1.0.0"
# APIの説明
description: "productsテーブルのレコードを登録・更新・取得・削除するAPI"
#APIのホスト名
host: "localhost:8000"
#API共通のpathを記載する
basePath: "/api/v1"
# 対象のテーブル名?を書く
tags:
- name: "products"
description: "productsテーブル"
schemes:
# スキーマ
- "http"
# APIのエントリポイントを記述
paths:
#URIを記載する
/products:
# GETリクエスト
get:
# 前述したタグ名
tags:
- "products"
#概要
summary: "商品情報取得"
#詳細説明
description: "productsテーブルに登録されている商品情報を全件取得する"
# content-typeの指定
produces:
- "application/json"
# レスポンスに関する記述
responses:
#statusCode200の時
200:
description: "成功"
# レスポンスのbodyについて記述する
schema:
# jsonの場合,だけ？objectを指定する
type: "object"
# bodyの中身(ダミー値でいい)
properties:
id:
#データ型
type: "integer"
#ダミー値
example: "1"
name:
type: "string"
example: "hogehoge"
# POSTリクエスト
post:
tags:
- "products"
summary: "商品情報登録"
description: "商品情報をproductsテーブルに1件登録する"
produces:
- "application/json"
# リクエストのbodyについて記述する
parameters:
# パラメータの名前
- name: "body"
# パラメータの場所
in: "body"
required: true
schema:
type: "object"
properties:
name:
type: "string"
example: "piyopiyo"
responses:
200:
description: "成功"
schema:
type: "object"
properties:
id:
type: "integer"
example: "2"
name:
type: "string"
example: "piyopiyo"
400:
description: "失敗"
schema:
type: "object"
properties:
message:
type: "string"
example: "Bad Request"
# リクエストによって値が変わるパラメータは`{}`で囲む
/model1/{id}:
# PUTリクエスト
put:
tags:
- "products"
summary: "商品情報更新"
description: "URIで指定したidのproductsテーブルの商品情報を更新する"
produces:
- "application/json"
parameters:
- name: "id"
in: "path"
description: "更新対象のid"
required: true
# データ型
type: "integer"
- name: "body"
in: "body"
description: "更新内容"
required: true
schema:
type: "object"
properties:
name:
type: "string"
example: "fugafuga"
responses:
200:
description: "成功"
schema:
type: "object"
properties:
id:
type: "integer"
example: "1"
name:
type: "string"
example: "fugafuga"
400:
description: "失敗"
schema:
type: "object"
properties:
message:
type: "string"
example: "Bad Request"
# DELETEリクエスト
delete:
tags:
- "products"
summary: "商品情報削除"
description: "URIで指定したidのproductsテーブルの商品情報を削除する"
produces:
- "apllication/json"
parameters:
- name: "id"
in: "path"
description: "削除対象の商品id"
required: true
type: "integer"
responses:
204:
description: "削除の戻り値"
プレビュー
こんな感じになりました(うまくスクショ取れずすみません🙏)
おまけ
レスポンスbodyのjsonの階層を深くしたい場合は下記の様に記述すればいけます！👍
responses:
#statusCode200の時
200:
description: "成功"
# レスポンスのbodyについて記述する
schema:
# jsonの場合,だけ？objectを指定する
type: "object"
# bodyの中身(ダミー値でいい)
properties:
status:
type: "integer"
example: "200"
products:
properties:
id:
#データ型
type: "integer"
#ダミー値
example: "1"
name:
type: "string"
example: "hogehoge"
スクショ
おわり
次はhtml生成するところやりたいと思います
参照
Swaggerでいますぐドキュメントを書きたい/読みたい人のためのセットアップガイド
開発効率を上げる！Swaggerの記法まとめ