Github Actionsを用いてAPI定義書のコード管理をしたらちょっと幸せになった話

はじめに

• プロジェクトによりけりではあるのですが、最近、段々とAPI定義書をコード管理する習慣ができてきました！
• 簡易なシステムではあるのですがご紹介だけ！

全体のフロー

1. 特定ブランチへのマージ
2. openapi.jsonの生成
3. Redocドキュメントの生成(html)
4. S3へのアップロード

Github Actionsワークフロー

• Github Actionsを用いてOpenAPIフォーマットの生成〜アップロードを実現しています。
• ワークフロー自体は必要なライブラリのインストールであったりと長々つらつらと書いてますが、実ステップは以下3つでかなり手軽です！
• ※ 実際にはyarnで実行する為にスクリプト化してるので、実際に実行してるコマンドだけ記載

①コードのアノテーションからopenapi.jsonを生成

$ node dist/script/export-openapi.js

②生成したopenapi.jsonを元にRedocドキュメントを生成

$ redoc-cli bundle openapi.json

③S3へのアップロード

$ aws s3 cp ./redoc-static.html s3://$S3_BUCKET_NAME/index.html

※ こちら↓はRedocのデモ版のイメージを拝借いたしました。

おまけ

• ついでにAPI定義変更の実施＆完了をチームメンバーに伝える目的でデプロイ実施後に成功/失敗をSlackに通知しています。

（ワークフロー定義ファイル一部抜粋）

      - name: Slack Notification on Success
        if: success()
        uses: rtCamp/action-slack-notify@v2.0.2
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          SLACK_USERNAME: Github Actions
          SLACK_ICON_EMOJI: ':github:'
          SLACK_COLOR: good
          SLACK_TITLE: API定義生成
          SLACK_MESSAGE: 成功しました

      - name: Slack Notification on Failure
        if: failure()
        uses: rtCamp/action-slack-notify@v2.0.2
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          SLACK_USERNAME: Github Actions
          SLACK_ICON_EMOJI: ':github:'
          SLACK_COLOR: danger
          SLACK_TITLE: API定義生成
          SLACK_MESSAGE: 失敗しました

おわりに

• Github Actions使ってみたいなぁという軽い気持ちで臨んだのですが、わりと簡単に作れるのでおすすめです！
• ただ、既存のコード側にOpenAPI用のアノテーションを記述していくのはなかなか大変だったので、あとから導入するのはもうコリゴリですw
• あと運用面で弊社の場合、フロントチームにAPI定義書をバックエンド実装前に渡す必要があるので、実装の前にAPI定義書作成用のコミットが必要になってしまいます。そこの運用方法については微妙だなと思ってるので改善案考えて取り組んでいきたいと考えています