使用 Github Action 自动更新开源项目 API 文档 • Usubeni Fantasy

场景

在更新一个开源库的时候，常常会增删改旧接口，这样的变动可能很频繁、细微，如果每次因此手动修改文档无疑是很繁琐的任务。因此亟需一条能自动解决以上问题的流水线。只要我发布了新版本，就会自动更新接口文档。

涉及技术

api-extractor，用于提取接口信息
api-documenter，将提取到的信息处理为 markdown 文件
docusaurus，老牌文档框架
GitHub Action，运行流水线自动提交文档文件

在这个情况下，我不希望 docusaurus 与我本来的代码库混到一块，所以分开两个项目管理。这就涉及到将内容一个提交到第三方仓库的能力了，本文以 mind-elixir-core 和 mind-elixir/docs 为例。

配置文件

name: Node.js Package

on:
  release:
    types: [created]
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          registry-url: "https://registry.npmjs.org"
          cache: "pnpm"
      - run: pnpm i
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

      - name: Checkout docs repository
        uses: actions/checkout@v3
        with:
          repository: mind-elixir/docs
          token: ${{ secrets.PAT }}
          path: me-docs

      - name: Generate API documentation
        run: |
          npm run doc
          npm run doc:md

      - name: Copy build results to docs repository
        run: |
          cp -r ./md/* ./me-docs/docs/api
          cp -r ./md/* ./me-docs/i18n/ja/docusaurus-plugin-content-docs/current
          cp -r ./md/* ./me-docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current

      - name: Push changes to docs repository
        run: |
          cd me-docs
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          if git diff-index --quiet HEAD; then
            echo "No changes to commit"
          else
            git commit -m "Update API documentation"
            git push
          fi

配置分析

push 操作的重点是在项目中配置 secrets.PAT。GitHub Action 运行的当前项目似乎是不需要 PAT 的，但如果推送到其他项目，PAT 就是必须的。

所谓的 PAT 其实就是 personal access token，带着它代表你有推送目标 GitHub 仓库的权限。

PAT 获取路径：

验证邮箱
点击 GitHub 右上角头像，选择 Settings
左侧栏选择 Developer settings
左侧栏选择 Personal access tokens

现时有两种 Token 可以选择，不过在 GitHub 内部使用 GitHub 的 Token，直接权限拉满大概也没什么问题。

拿到 PAT 之后在需要运行 Action 的仓库配置 secret，Action 在运行的时候就会自动取到。除此之外的内容就是一些显而易见的自动化脚本，不多加赘述，整体流程请看总结 ↓

总结

整个 GitHub Action 的基本流程就是：

拉取项目
构建项目
发布到 npm（需要 npm Token）
使用 api-extractor 提取接口信息，使用 api-documenter 生成 markdown 文件
拉取文档项目
把上面生成的 markdown 文档文件复制到文档项目（因为做了 i18n 所以复制了三遍）
然后提交文档仓库更新就好了
文档仓库更新后也会自动触发自己的 webhook 自动构建文档站

这么一套下来，mind-elixir-core 版本发布后，文档网站的 API 分区就能自动更新啦。