【備忘録】OpenAPIからredocでAPIドキュメント生成 + TS型定義を生成してnpmレジストリに公開するGitHub Actionsを作成する

はじめに

以下2点をGitHub Actionsで実行する備忘録です。

• OpenAPIからredocでAPIドキュメントを生成してGitHub Pagesにデプロイする
• OpenAPIからTypeScript型定義を生成してnpmレジストリに公開する

redoc側のActions

.github/workflows/deploy-redoc.yml

name: OpenAPIをredocとしてgithub pagesにデプロイする

on:
  push:
    branches:
      - main
    paths:
      - "openapi/*" # OpenAPIのyamlだけをCI対象にする
  workflow_dispatch: # 手動実行用

jobs:
  build-redoc:
    runs-on: ubuntu-latest
    steps:
      # リポジトリを取得する
      - uses: actions/checkout@v4

      - name: redocを生成する
        run: npx @redocly/cli build-docs ./openapi/openapi.yaml -o ./docs/envhub-api-docs.html

      - name: artifactsとして生成したredocを保存する
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs

  deploy-redoc:
    needs: build-redoc
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
      
    steps:
      - name: GitHub pagesにデプロイする
        id: deployment
        uses: actions/deploy-pages@v4

TypeScript型生成側のActions

.github/workflows/publish-npm-typescript.yml

name: OpenAPIからTypeScriptの型定義を作成してnpmにpublishする

on:
  push:
    branches:
    - main
    paths:
      - "openapi/*" # OpenAPIのyamlだけをCI対象にする
  workflow_dispatch: # 手動実行用

jobs:
  build-typescript:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write

    steps:
      # リポジトリを取得する
      - uses: actions/checkout@v4

      # publishするために.npmrcに認証情報を読み込む
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'

      - name: npm installする
        run: npm install --ignore-scripts

      - name: TypeScriptの型定義を生成する
        run: npx @hey-api/openapi-ts -i openapi/openapi.yaml -o src/client -c @hey-api/client-fetch

      - name: 生成したTypeScriptの型をnpmに公開できるようにトランスパイルする
        run: npx tsc

      - name: npmにpublishする
        run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

使い方

1. openapi/openapi.yamlを編集する
2. package.jsonのversionを上げる
3.mainにpushする

さいごに

以下リンクが実装したリポジトリです。