logo header
logo header
logo header
logo header
  • 2016.12.20
  • 技術ブログ

SwaggerエディターでREST APIの設計書を書いてみる

先月発売された某ゲームで食材集めに余念がないzukaです。

前回の続きを書く予定でしたが、業務でREST APIの設計書を書く機会があっため、今回はこちらについて書こうと思います。

はじめに

みなさんはREST APIを設計するとき、どのようなツールを使って設計書を作成していますか?

自分は手軽さから、ついつい安直にExcelで作成していました。
しかし、Excelだと以下のような不都合に直面してしまいます。

 

  • Gitで管理するときに履歴が追いにくい
  • 複数人で同じExcelを修正するときに、マージが面倒
  • メンテナンスが面倒
  • 見るのも面倒

 

そこで、社内の有識者の方々に良いツールはないか尋ねてみたところ
Swagger」はどうだろうか、というご意見をいただきました。

Excelを卒業するため、早速SwaggerでREST APIの設計書を作成してみたいと思います。

前提

ここからは、以下の前提条件が満たされていることを前提とします。

  • npmがインストール済みであること。
  • Node.jsがインストール済みであること。
  • Dockerがインストール済みであること。

SWAGGER EDITORを起動する

では、早速必要なツールを準備してみます。
設計書は「SWAGGER EDITOR」を使用して記載します。

SWAGGER EDITORはDockerで起動させるか、ローカルのHTTPサーバで起動させるか、2通りの方法で起動させるようです。
Dockerで起動した方が楽なので、Dockerで起動します。

起動方法はこちらの「Running with Docker」に記載があります。
リポジトリが公開されていますので、ありがたくこちらを使用させてもらいます。
起動方法は記載があるとおりなので、とても簡単です!

 

起動したら、ブラウザで「http://localhost:80」にアクセスしてみます。
このような画面が表示されました。

SWAGGER EDITORで設計書を書いてみる

メニューの「File > New」を選択します。

 

新しいファイルができあがるので、あとはガリガリ必要な箇所を記載していきます。
デフォルトのフォーマットが最初から表示されているので、YAML形式で記載します。
自分は以下のように変更してみました。

 

  • 「info」の「version」「title」を変更
  • 「info」に「description」を追加(自動補完機能があるようです)
  • 「schemes」「basePath」「produces」を追加
  • 「paths」以降を変更

 

書き方については、こちらが参考になります。

 

YAMLとJSON形式でファイルを保存することもできます。

HTMLに出力してみる

YAMLやJSONですと、設計書としてはあまり見やすくありません。
そこで、誰でも見れるようにHTMLに出力してみたいと思います。

HTMLで出力するには、bootprint-openapiで出力できるようです。
まずはインストールします。

あとはファイルを指定して以下のコマンドを実行するだけです。

 

HTMLに出力されました。

まとめ

設計書とコードを連携させ、コードを変更すると設計書も変更される、という方法もあるようです。
常に最新の設計書を保つためにも、こちらもぜひ取り入れていきたいところです。

ともに世界をアップグレードできる、そんな日を夢見て。
Upgrade the World!