GitHub Actionsを使ってGithub PagesにOpen APIのドキュメントを公開したメモ

概要

pushしただけでドキュメントの公開をしたかったので自動デプロイを試してみた。
vercelでWebページの公開はできるので、余っているGithub PagesにOpenAPIのReDocを公開してみる。

ソースコード

2021.11.3 追記

openapi3.1に対応したソースコード ... swagger-cli不要で、redocのみでよくなった。

ディレクトリ構成

- .github
  - workflows
    - gh-pages.yml      ... GitHub Actions記述
- src ... ソースコード
- docs
  - index.html          ... 各ドキュメントへのリンクを張るのみのHTML
- internals             ... 内部使用ドキュメントツールを入れるディレクトリ
  - api-schema          ... OpenAPIを記述

OpenAPI

yamlの作成

GitHub Actions による GitHub Pages への自動デプロイを参考に、yamlファイルを作成する。

.github/workflows/gh-pages.yml

name: github pages

on:
  push:
    branches:
      - docs  # Set a branch name to trigger deployment

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '14'

      - name: OpenAPI Setup
        run: npm ci
        working-directory: ./internals/api-schema

      - name: OpenAPI Make
        run: npm run redoc
        working-directory: ./internals/api-schema


      - name: OpenAPI Move files
        run: |
          mkdir -p ./docs/publish/api-schema
          mv ./internals/api-schema/dist/index.html ./docs/publish/api-schema/

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

作成したら、docsブランチをpushする。
push後、Actionsを確認して、デプロイされていることを確認する。

ブランチに、gh-pagesが新しくできていることを確認する。
デプロイされたファイルがgh-pagesに配置されていることを確認する。

github pagesの有効化

• settings をスクロールしていくと「Github Pages」の項目があるので設定をする。
  • 「/(root)」か「/docs」のいずれか。今回はActionsの公開先である「/(root)」を選択する。
  • 「Save」すると、公開先のURLが表示される
    

参考

GitHub Actions による GitHub Pages への自動デプロイ
AsciidocのドキュメントをGitHub Actionsを用いてGitHub Pagesで公開する
GitHub Actionsのワークフロー構文
公開元を設定する