API仕様書にOpenAPIを使用して感じた良さ

こんにちは、オープンワークのアプリ開発チームでサーバーサイドエンジニアをやっている濱田です。

アプリ開発チームでは当初、開発速度を優先しAPI仕様書をGoogleスプレッドシートに書いていました。しかしこの度無事にOpenAPIに移行できたのでその感想をお伝えしたいと思います。

書くこと

検討したこと
ドキュメントの管理方法
OpenAPIにしてよかったこと

書かないこと

OpenAPIとは
OpenAPIドキュメントの書き方

スプレッドシートに書いていた頃の問題点

1. 見づらい

エンドポイントの一覧、レスポンスのモデル、そして個別のAPI仕様をテーブルに書いただけなので当然ですね。また、それを改善できるスプレッドシートスキルもありませんでした。

2. 更新履歴が残せない

差分は文字色を黒以外にすることで示していました。時間が経てば黒色に戻しますし、その期間も属人的な感覚や開発の進捗に依存していました。そもそも戻すことを忘れてずっと放置してしまうこともよくありました。

3. 一定のフォーマットがない

一定のフォーマットがなかったため、慣れの程度によって記述のゆらぎが生じていました。

OpenAPIへの移行

保守性や将来の引き継ぎのことを考えるとスプレッドシート＋社内ルールでの仕様書作成を続けるのは不安があります。

そこで統一的なフォーマットである「OpenAPI」への移行を検討し始めました。開始時点でのレスポンスのモデルは約30個、エンドポイントは約50個、かかった期間は開発の合間に進めながら２週間です。

検討事項

1. yaml vs json

yamlとjsonどちらでも記述可能ですが、下記の理由によりyamlに優位があると判断しました。

公式ドキュメントはyamlで書かれている
ウェブ上のエントリもyamlで書かれていることが多い
コメントが書ける

2. 公式UI vs サードパーティ製UI

yamlで書いたドキュメントファイルをブラウザ上で閲覧できるようのHTMLジェネレータを使用する必要があります。
公式UI（SwaggerUI）は悪くないですが、エンドポイントの増加に応じて無限に長くなっていくのが気になります。

そこでこちらの記事を参考にサードパーティのHTMLジェネレータを検討し、下記の理由からredocを採用することにしました。

GitHubスターの多さ（6000↑）
開発の活発さ
すっきりした見た目

github.com

3. 共有方法

せっかくドキュメントを書いたのでチーム内で閲覧できるようにしないといけません。
redoc-cliを使うと、OpenAPIドキュメントから外部依存のない静的なHTMLファイルを出力できます。こちらをBacklogの共有フォルダに置き、ブラウザから閲覧することにしました（参考）。

ドキュメント管理方法

ドキュメントの更新をしていくための管理方法です。ディレクトリは大きく２つに分けています。

├── 📁 doc
│   ├── 📄 index.yml
│   ├── 📁 paths
│   └── 📁 components
│
└── 📁 tool
    ├── 📄 package.json
    ├── 📄 template.hbs
    └── 📁 node_modules

doc

OpenAPIドキュメントのyamlファイルのみを格納しています。
index.ymlをエントリポイントとしてpathsとcomponentsは個別のファイルに分けています。記述方法については公式ドキュメントはじめ世に多くの記事があるので今回は省略します。

tool

npmパッケージや各種コマンドなどを管理しています。
template.hbsはredoc-cliのデフォルトテンプレートです。作業に必要なコマンドはpackage.jsonに定義してあります。

{
  // commit前にprettierでyamlをフォーマットしています。
  "husky": {
    "hooks": {
      "pre-commit": "pretty-quick --staged --pattern **/*.yml"
    }
  },
  "scripts": {
    // 編集作業用です。yamlファイルの変更を監視しながらhtmlファイルを吐いてくれます。
    "dev": "node_modules/.bin/redoc-cli serve ../doc/index.yml-t template.hbs --watch",

    // 公開用にyamlファイルをバンドルします。
    "bundle": "node_modules/.bin/swagger-merger -i ../doc/index.yml -o compiled.yml",

    // 公開用htmlファイルを出力します。
    "prod": "node_modules/.bin/redoc-cli bundle compiled.yml -t template.hbs -o apidoc.html",

    // 公開用です。実際にはhtmlファイルアップロード処理が後に続きます。
    "publish": "npm run bundle && npm run prod",
  },
  "dependencies": {
    "husky": "^3.0.3",
    "prettier": "^1.18.2",
    "pretty-quick": "^1.11.1",
    "redoc-cli": "^0.8.5",
    "swagger-merger": "^1.4.3"
  }
}

移行して感じた良さ

まず見やすいUIになったこと。これはOpenAPIそのものではなくredocによるものですが、「見やすさ」について頑張らなくてよくなり、API仕様の記述のみに集中できるので作業効率が向上しました。
またプルリクによるレビューが可能なことや、設定をPostmanへ取り込み共有できるようになったことでチーム開発への親和性も高まったようにも思います。

そして何よりも統一された記述フォーマットがあることです。
記述の自由さという点では当然スプレッドシートに軍配が上がります。学習コストもありません。

しかしその自由さはドキュメント記述においては「割れ窓理論」で言うところの割れ窓になりうるリスクがあると考えています。厳密なフォーマットがなければ、ときにその場の思いつきによる記述をしてしまい、それがコピペされ増えることで全体の品質が低下していくということです。
対してOpenAPIは記述するべきこととその方法が厳密に定められており、一度そのルールに乗っかることを覚えれば本質的な内容の記述のみに集中できる利点があります。

OpenAPIは公式ドキュメントが英語しかないこともあり、正直なところ学習コストは高くつきました。しかしスプレッドシートから移行できたことによって得られた恩恵は確実にあったように思います。
これからAPI仕様書をつくる方、現在の管理方法に悩んでいる方はぜひ検討してみてはいかがでしょうか。

(※本記事は2019年9月13日にWantedlyに掲載した記事を移行したものになります)