概要

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

これでブラウザが起動します!

スクリーンショット 2018-05-10 16.00.40.png

あとはヘッダーから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: "削除の戻り値"

プレビュー

こんな感じになりました(うまくスクショ取れずすみません🙏)

スクリーンショット 2018-05-10 22.04.56.png
スクリーンショット 2018-05-10 22.05.08.png
スクリーンショット 2018-05-10 22.05.20.png
スクリーンショット 2018-05-10 22.05.30.png
スクリーンショット 2018-05-10 22.05.39.png

おまけ

レスポンス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"

スクショ

スクリーンショット 2018-05-10 22.24.44.png

おわり

次はhtml生成するところやりたいと思います

参照

Swaggerでいますぐドキュメントを書きたい/読みたい人のためのセットアップガイド
開発効率を上げる!Swaggerの記法まとめ

Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account log in.