From 69a3dd8a39d254044c3cc2021c87d267ce659ed0 Mon Sep 17 00:00:00 2001 From: Muhammad Faraz Maqsood Date: Tue, 25 Aug 2026 18:09:00 +0500 Subject: [PATCH 1/3] feat: add GH workflow to generate openapi schema Add GH workflow to automatically generate openapi schema whenever view file tagged with the "openedx-platform-sdk" @extend_schema tag changes --- .../workflows/generate_openapi_schemas.yml | 103 ++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 .github/workflows/generate_openapi_schemas.yml diff --git a/.github/workflows/generate_openapi_schemas.yml b/.github/workflows/generate_openapi_schemas.yml new file mode 100644 index 000000000000..26f9555c081a --- /dev/null +++ b/.github/workflows/generate_openapi_schemas.yml @@ -0,0 +1,103 @@ +# generate_openapi_schemas.yml +# +# Purpose: Generate OpenAPI schemas for the LMS and CMS using drf-spectacular, +# then open a pull request if either schema changed. The generated schema files +# are consumed by the openedx-platform-sdk repo's regen_sdk.sh script to keep +# the SDK in sync with the platform's tagged API views. +# +# Tuning notes: +# - The settings modules below (lms.envs.production / cms.envs.production) +# must have SPECTACULAR_SETTINGS configured. Adjust if your environment +# uses a different settings module (e.g. lms.envs.devstack). +# - The requirements path (requirements/edx/base.txt) may need adjustment +# depending on your local layout or if drf-spectacular lives in a different +# requirements file. + +name: Generate OpenAPI Schemas + +permissions: + contents: write + pull-requests: write + +on: + workflow_dispatch: + + push: + branches: + - master + paths: + # Triggers whenever a view file tagged with the openedx-platform-sdk + # @extend_schema tag changes — add new tagged view paths here as more + # APIs are onboarded to the SDK. + # + # LMS — Enrollment v2 + - 'openedx/core/djangoapps/enrollments/**' + # CMS — XBlock v1, Home v3/v4, Course Details v3, Authoring Grading v3 + - 'cms/djangoapps/contentstore/rest_api/v1/views/xblock.py' + - 'cms/djangoapps/contentstore/rest_api/v3/views/home.py' + - 'cms/djangoapps/contentstore/rest_api/v3/views/course_details.py' + - 'cms/djangoapps/contentstore/rest_api/v3/views/authoring_grading.py' + - 'cms/djangoapps/contentstore/rest_api/v4/views/home.py' + # drf-spectacular config changes in either service + - 'lms/lib/spectacular.py' + - 'cms/lib/spectacular.py' + - 'lms/envs/common.py' + - 'cms/envs/common.py' + +jobs: + generate-schemas: + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install dependencies + run: | + pip install --upgrade pip + # Note: adjust this path if drf-spectacular is in a different requirements file + pip install -r requirements/edx/base.txt + + - name: Generate LMS OpenAPI schema + run: | + # SPECTACULAR_SETTINGS must be present in the settings module used here. + # Switch to a lighter settings module if production settings require + # environment variables or external services that are unavailable in CI. + python manage.py spectacular \ + --settings=lms.envs.production \ + --file lms_schema.yml + + - name: Generate CMS OpenAPI schema + run: | + # Same note as above — SPECTACULAR_SETTINGS must be available. + python manage.py spectacular \ + --settings=cms.envs.production \ + --file cms_schema.yml + + - name: Open pull request if schemas changed + uses: peter-evans/create-pull-request@v6 + with: + branch: chore/update-openapi-schemas + commit-message: 'chore: regenerate OpenAPI schemas' + title: 'chore: update OpenAPI schemas for SDK generation' + body: | + ## Auto-generated OpenAPI schema update + + This PR was opened automatically by the **Generate OpenAPI Schemas** workflow. + It contains regenerated `lms_schema.yml` and/or `cms_schema.yml` files + reflecting the latest state of the platform's tagged API views. + + These schema files are used by the + [openedx-platform-sdk](https://github.com/your-org/openedx-platform-sdk) + repository's `regen_sdk.sh` script to keep the SDK client in sync with + the platform. Update the link above once the SDK repo URL is finalised. + + **Do not edit these files by hand** — they will be overwritten on the next run. + add-paths: | + lms_schema.yml + cms_schema.yml From 48831c3fb0ca8ec5acc33a12b872b628baaa2c63 Mon Sep 17 00:00:00 2001 From: Muhammad Faraz Maqsood Date: Wed, 9 Sep 2026 16:03:51 +0500 Subject: [PATCH 2/3] feat: address comments --- .../workflows/generate_openapi_schemas.yml | 43 ++++++------------- 1 file changed, 12 insertions(+), 31 deletions(-) diff --git a/.github/workflows/generate_openapi_schemas.yml b/.github/workflows/generate_openapi_schemas.yml index 26f9555c081a..d5ac4838f38f 100644 --- a/.github/workflows/generate_openapi_schemas.yml +++ b/.github/workflows/generate_openapi_schemas.yml @@ -4,14 +4,6 @@ # then open a pull request if either schema changed. The generated schema files # are consumed by the openedx-platform-sdk repo's regen_sdk.sh script to keep # the SDK in sync with the platform's tagged API views. -# -# Tuning notes: -# - The settings modules below (lms.envs.production / cms.envs.production) -# must have SPECTACULAR_SETTINGS configured. Adjust if your environment -# uses a different settings module (e.g. lms.envs.devstack). -# - The requirements path (requirements/edx/base.txt) may need adjustment -# depending on your local layout or if drf-spectacular lives in a different -# requirements file. name: Generate OpenAPI Schemas @@ -50,37 +42,24 @@ jobs: steps: - name: Check out repository - uses: actions/checkout@v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - - name: Set up Python 3.12 - uses: actions/setup-python@v5 + - name: Install uv + uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0 with: - python-version: '3.12' + enable-cache: true - name: Install dependencies - run: | - pip install --upgrade pip - # Note: adjust this path if drf-spectacular is in a different requirements file - pip install -r requirements/edx/base.txt + run: uv sync --frozen - name: Generate LMS OpenAPI schema - run: | - # SPECTACULAR_SETTINGS must be present in the settings module used here. - # Switch to a lighter settings module if production settings require - # environment variables or external services that are unavailable in CI. - python manage.py spectacular \ - --settings=lms.envs.production \ - --file lms_schema.yml + run: uv run python manage.py lms spectacular --file lms_schema.yml - name: Generate CMS OpenAPI schema - run: | - # Same note as above — SPECTACULAR_SETTINGS must be available. - python manage.py spectacular \ - --settings=cms.envs.production \ - --file cms_schema.yml + run: uv run python manage.py cms spectacular --file cms_schema.yml - name: Open pull request if schemas changed - uses: peter-evans/create-pull-request@v6 + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8 with: branch: chore/update-openapi-schemas commit-message: 'chore: regenerate OpenAPI schemas' @@ -93,11 +72,13 @@ jobs: reflecting the latest state of the platform's tagged API views. These schema files are used by the - [openedx-platform-sdk](https://github.com/your-org/openedx-platform-sdk) + [openedx-platform-sdk](https://github.com/edly-io/openedx-platform-sdk) repository's `regen_sdk.sh` script to keep the SDK client in sync with - the platform. Update the link above once the SDK repo URL is finalised. + the platform. **Do not edit these files by hand** — they will be overwritten on the next run. + + @openedx/wg-maintenance-openedx-platform-oncall heads up on this automated PR. add-paths: | lms_schema.yml cms_schema.yml From ff17ccaf3b1f5ad68f01acd029124c10d67bebef Mon Sep 17 00:00:00 2001 From: Muhammad Faraz Maqsood Date: Thu, 10 Sep 2026 18:09:54 +0500 Subject: [PATCH 3/3] fix: address comments on generate schemas workflow address comments on generate_openapi_schemas workflow - weekly schedule - use team-reviewers param --- .../workflows/generate_openapi_schemas.yml | 27 +++---------------- 1 file changed, 4 insertions(+), 23 deletions(-) diff --git a/.github/workflows/generate_openapi_schemas.yml b/.github/workflows/generate_openapi_schemas.yml index d5ac4838f38f..a2334315bab7 100644 --- a/.github/workflows/generate_openapi_schemas.yml +++ b/.github/workflows/generate_openapi_schemas.yml @@ -14,27 +14,9 @@ permissions: on: workflow_dispatch: - push: - branches: - - master - paths: - # Triggers whenever a view file tagged with the openedx-platform-sdk - # @extend_schema tag changes — add new tagged view paths here as more - # APIs are onboarded to the SDK. - # - # LMS — Enrollment v2 - - 'openedx/core/djangoapps/enrollments/**' - # CMS — XBlock v1, Home v3/v4, Course Details v3, Authoring Grading v3 - - 'cms/djangoapps/contentstore/rest_api/v1/views/xblock.py' - - 'cms/djangoapps/contentstore/rest_api/v3/views/home.py' - - 'cms/djangoapps/contentstore/rest_api/v3/views/course_details.py' - - 'cms/djangoapps/contentstore/rest_api/v3/views/authoring_grading.py' - - 'cms/djangoapps/contentstore/rest_api/v4/views/home.py' - # drf-spectacular config changes in either service - - 'lms/lib/spectacular.py' - - 'cms/lib/spectacular.py' - - 'lms/envs/common.py' - - 'cms/envs/common.py' + schedule: + # Regenerate and commit the full OpenAPI schemas every Monday at 09:00 UTC. + - cron: "0 9 * * 1" jobs: generate-schemas: @@ -64,6 +46,7 @@ jobs: branch: chore/update-openapi-schemas commit-message: 'chore: regenerate OpenAPI schemas' title: 'chore: update OpenAPI schemas for SDK generation' + team-reviewers: wg-maintenance-openedx-platform-oncall body: | ## Auto-generated OpenAPI schema update @@ -77,8 +60,6 @@ jobs: the platform. **Do not edit these files by hand** — they will be overwritten on the next run. - - @openedx/wg-maintenance-openedx-platform-oncall heads up on this automated PR. add-paths: | lms_schema.yml cms_schema.yml