Zenn
🔒

Cloudflare Accessを使ってAPIスキーマを安全に共有する

2025/01/15に公開
Cloudflare
OpenAPI
Cloudflare Pages
tech

スキーマ共有

みなさん、バックエンドとフロントエンド間のスキーマ共有はどのようにしていますか？
会社での業務であればそのあたりはすでに整備されていることが多く、各々の方法で簡単に共有ができていると思います。

しかし複数人でのプライベートな開発ではなかなかそういった部分に時間が割けず、その都度チャットでやりとりしたり、Notionなどにまとめたりということも少なくないのではないでしょうか。

その問題を解決するためにCloudflare PagesとCloudflare Accessだけで簡単に、そして安全に共有する方法を紹介します。

Open API

私たちはOpenAPIでスキーマを記述し、フロントエンドはopenapi-generator-cliを使ってAPIクライアントを自動生成しています。

schema.ymlからHTMLを生成

そのままのスキーマでは見通しが悪いのでredoc-cliを使ってHTMLを生成していきます。

redoc-cliはデフォルトでキレイなUIを作成してくれるのでとても便利です。


画像取得元

実際のコマンドは以下のようになります。

"codegen:html": "redoc-cli bundle src/libs/openapi/schema.yml --output dist/index.html"

bundleの後にスキーマへのパスを記述し、--outputで生成先のパスを指定します。

Cloudflare Pagesにデプロイ

上記で生成したHTMLをCloudflare Pagesを使ってデプロイしていきます。

ここではGithub Actionsを使って自動でデプロイするフローを考えます。
cloudflare/wrangler-actionを使えばapiTokenとaccountIdを用意するだけで大丈夫です。

GitHubに接続する

実際にCIを動かす前にWorker&Pagesからアプリケーションを作成する必要があります。
CreateからConnect to Gitを選択するとGitHubのリポジトリと接続することができます。

Build Settingは以下のように設定しておけば問題ないでしょう。都度プロジェクトに合わせて変更してください。

APIトークン作成

CIからデプロイするためAPIトークンが必要となります。

Workers&Pages→Manage API tokensで設定できます。

Create Custom TokenでPermissionを以下のようにすれば問題なく動きます。

PagesにデプロイするActions

--project-nameには先ほど作成したPagesのプロジェクト名をいれます。

cloudflare-hosting-api-doc.yml
name: Deploy API docs to Cloudflare Pages
'on':
  push:
    branches:
      - develop

     
jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: .node-version

      - name: Install dependencies and build
        run: npm ci && npm run codegen:html
      
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          command: pages deploy dist --project-name=<project name>

Cloudflare Accessを適用

ここまでの簡単なステップでCIからスキーマをビルドし、デプロイする流れができました。

しかし現状では誰でもページにアクセスできてしまいます。これではチーム内のスキーマが世界中に共有されてしまうのでアクセス制御する必要があります。

そこで今回はCloudflare Zero TrustのCloudflare Accessを使います。

タブのZero Trustからプラン選択をしますが、今回はfreeプランを使用することにします。

Access groupsを作成する

タブのAccess groupsを選択し、Define group criteriaからEmailsを選択し、チームメンバーのメールアドレスを追加していきます。

Access Policyからチームを適用

グループが作成できたらPagesの画面に戻り、設定からAccess Policyをオンにします。

オンにするとManageというボタンが出てくるので、そこからCloudflare Accessのページへ遷移します。

そして作成したプロジェクトに先ほどのグループを適用させれば、公開されたスキーマのアクセス制御が完成します！🎉

適用後の画面

適切に設定が完了していると以下のようにアクセス時にOTPが求められるようになっています。

めでたしめでたし🎉

Discussion