API仕様書をSwaggerとGitHubで管理することになった話

  • このエントリーをはてなブックマークに追加
  • LINEで送る

 こんにちは! 株式会社AilaB の山口央士朗(おうじろう)です。
 エンジニアチームではAPI仕様書をテキストベースで管理していましたが、つい先日、SwaggerというAPI仕様を管理するOSSフレームワークに移行しました。
 また、APIの仕様を記載したファイルをGitHub内に置くことによってバージョン管理を行うようにしましたので、その時の話をいたします。

目次

  • API仕様書をSwaggerとGitHub管理することになった経緯
  • ドキュメント管理方法
    • 使用ツール
    • 導入手順
    • 記述を行うときにやること
    • UIを確認するときにやること
  • SwaggerとGitHubで管理して良かった点
    • 仕様が見やすくなった
    • APIの差分がわかりやすくなった
    • APIの管理がしやすくなった
    • APIのレビュー/相談がしやすくなった
  • まとめ

API仕様書をSwaggerとGitHub管理することになった経緯

 SwaggerとGitHubで管理する前はドキュメント共有ツールを使っていましたが

  • APIの制約事項やパラメータが見にくい
  • 個人間でドキュメントの書き方にばらつきが発生する
  • APIの仕様変更時に変更点がわかりにくい
  • すでに作成済みのAPIなのか、今後作成する予定のAPIなのか管理/判断することが難しい

 という理由から、従来の管理方法に限界を感じていました。
 そこで、思い切ってAPI仕様書をSwaggerとGitHubに移行したという次第です。

ドキュメント管理方法

 様々な管理方法があるかと思いますが、今回は下記の方法で導入/管理を行うことにしました。
 Swagger導入方法の詳細についてはたくさんの記事が上がっているため、そちらも参考にしていただければ幸いです。

使用ツール

  • VSCode
  • Swagger Viewer(VSCodeの拡張機能)
  • OpenAPI(Swagger)Editor(VSCodeの拡張機能、以下OpenAPI Editorと記載します)

導入手順

  1. GitHubにドキュメント管理用リポジトリを作成
  2. VSCodeにSwagger ViewerとOpenAPI Editorをインストール
  3. api.yamlファイルを作成し、Swaggerに沿って記載する

Swaggerの書き方について、Swagger Editor にサンプルコードとUIがありますので参考にしてください。

APIの記述について

 OpenAPI Editorが正しくインストールされるとVSCodeのサイドバーに下記アイコンが表示されます。urlやレスポンス一覧を見ながらドキュメント作成することができ、便利です。

OpenAPI Editorのアイコン

UIの確認について

 shift + alt + Pでコマンド一覧が表示されます。ここでPreview Swaggerを選択するとVSCode上でUIが表示されます。

Preview Swaggerを選択するとSwaggerのプレビュー画面が見える

SwaggerとGitHubで管理して良かった点

API仕様書が見やすくなった

 従来のテキストベースでの管理を行っている時は、どのようにすれば見やすいAPI仕様書になるのか常に考えていました。しかしSwaggerでは、定められたフォーマットにしたがって記載を行うだけで非常にわかりやすいAPI仕様書が出来上がります。
 API仕様書のデザインを考えるというストレスがなくなるということは、私にとって非常にありがたいことでした。

APIの変更部分がわかりやすくなった

 テキストベースでは履歴が追いにくいため、急な仕様変更が発生した場合の差分が非常にわかりにくくなってしまいます。しかし、GitHubで管理することによって、APIのどの部分が変わったのかコミット単位で確認することができ、非常にわかりやすくなりました。

APIの管理がしやすくなった

 テキストベースのAPI仕様書は管理/判断することが大変でしたが、実装されていないAPIに関する仕様記述は別ブランチで管理し、実装された時にマージをするなどの運用ルールを設けることで、APIの管理がしやすくなりました。

APIのレビューや相談がしやすくなった

 以上のメリットから、新規APIの実装や仕様変更に関して、APIのレビュー/相談が行いやすくなりました。

まとめ

 API仕様書をGitHubで管理することによって、APIの運用のしやすさが格段に上がりました。この経験を基に今後は下記のことを行っていこうと考えています。

ドキュメント運用ルールの作成

 GitHubでAPI仕様書を管理することにより、レビューが行いやすくなりました。今後APIの仕様を変更する際は、「1. APIの変更点に対してプルリクを行う」「2. レビューを行い、問題がなければマージしてドキュメントを反映する」という形で管理しようとしています。

Github Pagesに公開

 どうやら作成したAPI仕様書をGithub Pagesに公開できるようです。API仕様書が簡単に閲覧できるようになると思うので、方法について調査していきます。

他のドキュメントもGitHubで管理

 Swagger以外にもGitHubで管理した方が運用しやすいものがないか調査を行っています。GitHubで運用して良かったドキュメントは都度ブログで紹介できたらと思います。
 ドキュメント管理の方法で他にも気づいたことがあればブログにしていきたいと思っています。
 最後までお読みいただき、ありがとうございました!

SNSでもご購読できます。