API-to-SDK Regeneration with GitHub Actions

"""Export the API OpenAPI document to disk."""

import json
import sys
from pathlib import Path

from acme_api import create_app


def main() -> None:
    """Write the OpenAPI schema to disk."""
    output_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(
        "openapi.json",
    )
    app = create_app()
    output_path.write_text(
        json.dumps(app.openapi(), indent=2, sort_keys=True) + "\n",
        encoding="utf-8",
    )


if __name__ == "__main__":
    main()

[tasks.openapi]
description = "Export the API OpenAPI document."
run = "uv run python scripts/export_openapi.py openapi.json"

[tasks.generate]
description = "Regenerate the Python SDK from openapi.json."
run = """
rm -rf generated/acme-api-client
uv run openapi-python-client generate \
  --path openapi.json \
  --config openapi-python-client.yaml \
  --meta uv \
  --output-path generated/acme-api-client \
  --overwrite
"""

[tasks.lint]
description = "Run strict Ruff checks."
run = "uv run ruff check ."

[tasks.test]
description = "Run SDK tests."
run = "uv run pytest"

name: Update generated SDK

on:
  push:
    branches:
      - main
  workflow_dispatch:

concurrency:
  group: update-generated-sdk-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: read

env:
  SDK_REPOSITORY: acme-org/acme-sdk

jobs:
  update-sdk:
    name: Dispatch API commit to SDK
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout REST API
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Install mise tools
        uses: jdx/mise-action@v2
        with:
          install: true
          cache: true

      - name: Verify API can export OpenAPI schema
        run: |
          mise trust .mise.toml
          mise run sync
          mise run lint
          mise run test
          mise run openapi

      - name: Create SDK repository app token
        id: sdk-app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.SDK_APP_ID }}
          private-key: ${{ secrets.SDK_APP_PRIVATE_KEY }}
          owner: ${{ github.repository_owner }}
          repositories: acme-sdk

      - name: Dispatch SDK regeneration workflow
        env:
          GH_TOKEN: ${{ steps.sdk-app-token.outputs.token }}
        run: |
          gh api \
            --method POST \
            "repos/${SDK_REPOSITORY}/dispatches" \
            -f event_type='openapi-schema-updated' \
            -f client_payload[source_api_repo]="${GITHUB_REPOSITORY}" \
            -f client_payload[source_api_sha]="${GITHUB_SHA}" \
            -f client_payload[source_api_run_url]="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"

name: Update from REST API schema

on:
  repository_dispatch:
    types:
      - openapi-schema-updated
  workflow_dispatch:
    inputs:
      source_api_repo:
        required: true
        default: acme-org/acme-api
      source_api_sha:
        required: true
      source_api_run_url:
        required: false
        default: ""

concurrency:
  group: update-from-api-schema
  cancel-in-progress: false

permissions:
  contents: write
  pull-requests: write
  statuses: write

env:
  API_WORKDIR: api-repo
  SDK_UPDATE_BRANCH: bot/update-openapi-from-restapi

jobs:
  regenerate-sdk:
    name: Regenerate SDK and open PR
    runs-on: ubuntu-latest
    timeout-minutes: 15

- name: Resolve dispatch payload
  id: payload
  run: |
    if [ -n "${DISPATCH_SOURCE_API_REPO}" ]; then
      source_api_repo="${DISPATCH_SOURCE_API_REPO}"
      source_api_sha="${DISPATCH_SOURCE_API_SHA}"
      source_api_run_url="${DISPATCH_SOURCE_API_RUN_URL}"
    else
      source_api_repo="${INPUT_SOURCE_API_REPO}"
      source_api_sha="${INPUT_SOURCE_API_SHA}"
      source_api_run_url="${INPUT_SOURCE_API_RUN_URL}"
    fi

    if [ -z "${source_api_repo}" ]; then
      echo "Source API repo is required." >&2
      exit 1
    fi

    if [ -z "${source_api_sha}" ]; then
      echo "Source API SHA is required." >&2
      exit 1
    fi

    {
      echo "source_api_repo=${source_api_repo}"
      echo "source_api_sha=${source_api_sha}"
      echo "source_api_run_url=${source_api_run_url}"
    } >> "${GITHUB_ENV}"

    {
      echo "source_api_repo=${source_api_repo}"
      echo "source_api_sha=${source_api_sha}"
      echo "source_api_run_url=${source_api_run_url}"
    } >> "${GITHUB_OUTPUT}"
  env:
    DISPATCH_SOURCE_API_REPO: ${{ github.event.client_payload.source_api_repo }}
    DISPATCH_SOURCE_API_SHA: ${{ github.event.client_payload.source_api_sha }}
    DISPATCH_SOURCE_API_RUN_URL: ${{ github.event.client_payload.source_api_run_url }}
    INPUT_SOURCE_API_REPO: ${{ inputs.source_api_repo }}
    INPUT_SOURCE_API_SHA: ${{ inputs.source_api_sha }}
    INPUT_SOURCE_API_RUN_URL: ${{ inputs.source_api_run_url }}

- name: Checkout SDK
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
    path: sdk-repo
    persist-credentials: false

- name: Create API repository app token
  id: api-app-token
  uses: actions/create-github-app-token@v2
  with:
    app-id: ${{ vars.API_APP_ID }}
    private-key: ${{ secrets.API_APP_PRIVATE_KEY }}
    owner: ${{ github.repository_owner }}
    repositories: acme-api

- name: Checkout REST API source commit
  uses: actions/checkout@v4
  with:
    repository: ${{ steps.payload.outputs.source_api_repo }}
    ref: ${{ steps.payload.outputs.source_api_sha }}
    token: ${{ steps.api-app-token.outputs.token }}
    path: ${{ env.API_WORKDIR }}
    persist-credentials: false

- name: Export OpenAPI schema from API commit
  working-directory: ${{ env.API_WORKDIR }}
  run: |
    mise trust .mise.toml
    mise run sync
    mise run lint
    mise run test
    mise run openapi

- name: Regenerate SDK and analyze OpenAPI change
  id: openapi
  working-directory: sdk-repo
  run: |
    cp ../${API_WORKDIR}/openapi.json openapi.json
    mise trust .mise.toml
    mise run sync
    mise run generate
    uv run python scripts/analyze_openapi_change.py
    cat .openapi-change.env >> "${GITHUB_OUTPUT}"
    mise run lint
    mise run test

- name: Commit and push SDK update branch
  if: steps.changes.outputs.changed == 'true'
  working-directory: sdk-repo
  env:
    GH_TOKEN: ${{ github.token }}
    RELEASE_COMMIT_SUBJECT: ${{ steps.openapi.outputs.release_commit_subject }}
    RELEASE_COMMIT_FOOTER: ${{ steps.openapi.outputs.release_commit_footer }}
  run: |
    gh auth setup-git
    git config user.name "github-actions[bot]"
    git config user.email \
      "41898282+github-actions[bot]@users.noreply.github.com"
    git checkout -B "${SDK_UPDATE_BRANCH}"
    git add openapi.json generated
    commit_args=(
      -m "${RELEASE_COMMIT_SUBJECT}"
      -m "Source REST API commit: https://github.com/${source_api_repo}/commit/${source_api_sha}"
    )
    if [ -n "${RELEASE_COMMIT_FOOTER}" ]; then
      commit_args+=(-m "${RELEASE_COMMIT_FOOTER}")
    fi
    git commit "${commit_args[@]}"
    bot_sha=$(git rev-parse HEAD)
    git push --force-with-lease origin "${SDK_UPDATE_BRANCH}"
    gh api \
      --method POST \
      "repos/${GITHUB_REPOSITORY}/statuses/${bot_sha}" \
      -f state=success \
      -f context='SDK regeneration checks' \
      -f description='API export, SDK codegen, Ruff, and tests passed.' \
      -f target_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"

- name: Create or update SDK pull request
  if: steps.changes.outputs.changed == 'true'
  working-directory: sdk-repo
  env:
    GH_TOKEN: ${{ github.token }}
    SUMMARY_MARKDOWN: ${{ steps.openapi.outputs.summary_markdown }}
    NEXT_VERSION: ${{ steps.openapi.outputs.next_version }}
  run: |
    title="chore(sdk): regenerate from REST API schema (${NEXT_VERSION})"
    body_file=$(mktemp)
    {
      echo "Regenerated SDK from REST API main."
      echo
      echo "Source REST API commit:"
      echo "https://github.com/${source_api_repo}/commit/${source_api_sha}"
      echo
      printf '%s\n' "${SUMMARY_MARKDOWN}"
    } > "${body_file}"

    existing_pr=$(gh pr list \
      --head "${SDK_UPDATE_BRANCH}" \
      --base main \
      --state open \
      --json number \
      --jq '.[0].number // empty')

    if [ -n "${existing_pr}" ]; then
      gh pr edit "${existing_pr}" \
        --title "${title}" \
        --body-file "${body_file}"
      pr_number="${existing_pr}"
    else
      pr_url=$(gh pr create \
        --base main \
        --head "${SDK_UPDATE_BRANCH}" \
        --title "${title}" \
        --body-file "${body_file}")
      pr_number=$(gh pr view "${pr_url}" \
        --json number \
        --jq .number)
    fi

    gh pr edit "${pr_number}" \
      --add-label "generated,${{ steps.openapi.outputs.pr_label }}"

generated/acme-api-client/pyproject.toml

name: CI

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  quality:
    name: Lint and test
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout SDK
        uses: actions/checkout@v4

      - name: Install mise tools
        uses: jdx/mise-action@v2
        with:
          install: true
          cache: true

      - name: Run quality gates
        run: |
          mise trust .mise.toml
          mise run sync
          mise run lint
          mise run test

import json
from pathlib import Path

from attrs import fields

from acme_api_client.models import WidgetCreate


def test_widget_create_model_matches_openapi_schema() -> None:
    openapi = json.loads(Path("openapi.json").read_text(encoding="utf-8"))
    schema = openapi["components"]["schemas"]["WidgetCreate"]
    generated_field_names = {field.name for field in fields(WidgetCreate)}
    schema_property_names = set(schema["properties"])

    assert schema_property_names <= generated_field_names