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 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仕様書を作成しました

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

 

 

Follow me!

投稿者プロフィール

ハナコ

ハナコ