APIの仕様書を書くのにSwaggerをつかってみたところ思った以上に簡単でしたのでご紹介します。当方の検証環境は以下です。

マシン(OS) : Mac Book Pro (macOS Sierra ver 10.12.6)

ブラウザ :  Google Chrome(ver 60.0.3112.113)

Swaggerについて

あまり詳しく調べていませんが、Web Api用のドキュメントツール群だと思っています。以下のような部分に利点を感じています。

  • 仕様書のレイアウトを考えなくてよい
  • 仕様書を作成するとモックのAPIサーバを作成可能
  • 設定はyaml(もしくはjson)ファイルを使うので好きなエディタで編集可能

公式サイトへは以下リンクよりアクセスしてください。

https://swagger.io/

この記事ではエディターのセットアップ、APIの定義方法を簡単な例を交えて説明します。

Swaggerエディターのセットアップ

オンラインのエディターを使う方法もありますが、この記事ではローカルで実行する方法を紹介します。

まずは、SwaggerエディターをダウンロードしAPI仕様書を編集できるようにします。

  1. 以下URLより最新版のソースコードをダウンロード
    https://github.com/swagger-api/swagger-editor/releases
  2. zipを解凍しindex.htmlをブラウザで開く

こんな感じの画面が開きましたでしょうか。

次に、webAPIの仕様書を実際に書いてみます。例として用いるのは簡単なToDoアプリ用webAPIです。

ToDoアプリケーションの仕様書作成

以下のようなAPIの仕様書を作成していきます。

  • ToDoリストの登録,閲覧用のAPI
  • エントリポイントは以下の2つ
    • POST – /todo/ : 新規ToDo作成
    • GET – /todo/{todo_id} : todo_idのToDoを取得

以下のコードをSwagger Editorにコピペして下さい。

swagger: "2.0"
info:
  title: todoアプリ
  version: 0.0.1
  description: "todoアプリのwebAPI仕様書例"
host: "example.todo.com"
basePath: "/v1"
paths:
  /todo/:
    post:
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: "object"
          properties:
            id:
              type: "integer"
            title:
              type: "string"
            open_datetime:
              type: "string"
              format: "date-time"
            close_datetime:
              type: "string"
              format: "date-time"
      responses:
        201:
          description: "todoの作成成功時のレスポンス"
  /todo/{todo_id}:
    get:
      parameters:
      - in: "path"
        name: "todo_id"
        required: true
        type: "integer"
      responses:
        200:
          description: "成功時のレスポンス"
          schema:
            type: "object"
            properties:
              id:
                type: "integer"
              title:
                type: "string"
              open_datetime:
                type: "string"
                format: "date-time"
              close_datetime:
                type: "string"
                format: "date-time"

これで設定完了です。Swagger Editor上には画像のように表示されているかと思います。

次に設定した項目について軽く解説します。

Swaggerの設定項目について

Swaggerにおいて必須項目は以下の3つです。

  • swagger : Swaggerのバージョンを記載(2017年9月現在は2.0.0を指定)
  • info : APIの情報を記載(タイトル、APIの説明等)
  • paths : APIのエントリポイント毎に仕様を記載

例で使っている任意項目は以下2つです。

  • host : ホストのURLを指定します
  • basePath : エントリポイントのベースパスを指定します。

今回は紹介しませんが、任意項目の設定によってエントリポイントのグループ化、スキーマの定義と使い回し、認証方法の指定等も表現することも可能です。任意項目は、Swagger EditorのデフォルトプロジェクトであるPetstore APIで一通り設定してあるので、設定する際はそちらが参考になります。

まとめ

  • Swagger Editorをセットアップしました
  • 簡単なToDoアプリのAPI仕様書を作成しました

とても便利ですので、今後の仕事で使っていけたらと思います。

 

 

投稿者プロフィール

ハナコ
ハナコ