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)ファイルを使うので好きなエディタで編集可能
公式サイトへは以下リンクよりアクセスしてください。
この記事ではエディターのセットアップ、APIの定義方法を簡単な例を交えて説明します。
Swaggerエディターのセットアップ
オンラインのエディターを使う方法もありますが、この記事ではローカルで実行する方法を紹介します。
まずは、SwaggerエディターをダウンロードしAPI仕様書を編集できるようにします。
- 以下URLより最新版のソースコードをダウンロード
https://github.com/swagger-api/swagger-editor/releases - 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仕様書を作成しました
とても便利ですので、今後の仕事で使っていけたらと思います。
投稿者プロフィール
最新の投稿
- Android2019年4月15日【お手軽アプリ開発】bitriseの概要と設定例まとめ
- 開発・便利ツール2017年9月25日Hello Swagger!