GitHub ActionsでOpenAPIの静的HTMLを自動出力する（redocly/cli）

OpenAPIのYAMLファイルから可読性の高い・静的なHTMLを生成するツールはいくつかありますが、そのうちの一つがredoclyです。
非常にきれいなHTMLファイルにしてくれるので便利なのですが、他人に共有するにはYAMLを修正する度に redoclyを実行→HTMLファイルをアップロード していたので非常に面倒でした。

そこで、GitHub Actionsのお試しがてらGitHub上での自動出力を試してみたのでそのメモです。

ファイル構成

サンプルとしてOpenAPIのリポジトリから petstore.yaml を持ってきました。以下の通り配置しています。

$ tree -a
.
|-- .git
|-- .github
|   `-- workflows
|       `-- build-redocly-html.yml
|-- README.md
`-- petstore.yaml

GitHub Actions

.github/workflowsに以下のファイルを配置しました。

build-redocly-html.yaml

name: Build redocly HTML file
on: push
permissions:
  contents: read
jobs:
  run-redocly-cli:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          sparse-checkout: petstore.yaml
          sparse-checkout-cone-mode: false
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npx -y @redocly/cli build-docs petstore.yaml -o output/redocly-static.html
      - uses: actions/upload-artifact@v3
        with:
          name: redocly-html
          path: output/redocly-static.html

GitHub Actionsのworkflowが回ると、workflowのページからZIPでダウンロード可能になります。

まとめ

GitHubを参照できる相手にはGitHubのページで共有できるので便利に使えそうです。
GitHub Actionsを初めて使ってみましたが、非常に手軽に使用できますね。

redocly/cli自体はNode.jsで動くツールですが、GitHub ActionsのRunner上で動かすのでリポジトリ内にNode関連のファイルは不要です。こういった所でも強みを感じました。