feat: add GH workflow to generate openapi schema - #39025
Faraz32123 wants to merge 4 commits into
Conversation
Sorry, something went wrong.
Add GH workflow to automatically generate openapi schema whenever view file tagged with the "openedx-platform-sdk" @extend_schema tag changes
|
|
||
| - name: Install dependencies | ||
| run: | | ||
| pip install --upgrade pip |
There was a problem hiding this comment.
We're using uv in this repo now, see how we do this in other workflows and sync it up.
Sorry, something went wrong.
| --file cms_schema.yml | ||
|
|
||
| - name: Open pull request if schemas changed | ||
| uses: peter-evans/create-pull-request@v6 |
There was a problem hiding this comment.
This PR should tag the current on-call engineer via the @openedx/wg-maintenance-openedx-platform-oncall team.
Sorry, something went wrong.
| # 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 \ |
There was a problem hiding this comment.
Is there a reason this can't use the default settings file? Today it's the devstack settings file.
Sorry, something went wrong.
|
|
||
| **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. |
There was a problem hiding this comment.
Use team-reviewers parameter instead: https://github.com/peter-evans/create-pull-request
Sorry, something went wrong.
| 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' |
There was a problem hiding this comment.
Rather than running this on every change to these files, what about running this once weekly on any changes. That way we don't need to maintain a list of files here, any changes to any of our tagged schemas will get picked up.
Sorry, something went wrong.
address comments on generate_openapi_schemas workflow - weekly schedule - use team-reviewers param
- write to docs/lms-openapi.yaml and docs/cms-openapi.yaml instead of creating new schema files at the repo root - generate the LMS schema under docs.docs_settings so the workflow writes the same full API surface `make swagger` does, rather than overwriting the docs schema with the narrow SDK-facing one
openedx/openedx-platform#39025 writes the generated schemas to docs/lms-openapi.yaml and docs/cms-openapi.yaml instead of the repo root, so follow the sparse-checkout, the CI env vars, and the PLATFORM_DIR copy. The SDK's own local copies keep their cms_schema.yml / lms_schema.yml names.
| enable-cache: true | ||
|
|
||
| - name: Install dependencies | ||
| run: uv sync --frozen |
There was a problem hiding this comment.
uv sync --frozen installs no groups, default-groups = [] at pyproject.toml:260, so ora2 is missing and both schema steps die with ModuleNotFoundError: No module named 'openassessment'.
Use uv sync --no-default-groups --group docs --frozen, matching the other five workflows and .readthedocs.yaml.
Sorry, something went wrong.
| - name: Install dependencies | ||
| run: uv sync --frozen | ||
|
|
||
| # `docs.docs_settings` is what `make swagger` uses: it applies the |
There was a problem hiding this comment.
This comment describes #39108, not master. Without it SPECTACULAR_SETTINGS is the default at lms/envs/common.py:2156 and lms_api_filter keeps only /api/enrollment/v\d+/, so this step overwrites the published LMS reference with the enrollment-only subset.
Note the dependency in the description and land #39108 first. On top of it the step is correct: 481 paths against the 293 committed.
Sorry, something went wrong.
| uv run python manage.py lms spectacular --file docs/lms-openapi.yaml | ||
|
|
||
| - name: Generate CMS OpenAPI schema | ||
| run: uv run python manage.py cms spectacular --file docs/cms-openapi.yaml |
There was a problem hiding this comment.
This step fails on every run. manage.py cms defaults to cms.envs.devstack, which needs STUDIO_CFG, so settings raise ImproperlyConfigured and you get Unknown command: 'spectacular', exit 1.
Use cms.envs.development from #37444, which is on master now. That works: 236 paths, 56 under /api/contentstore. Heads up that it emits title: '' and version: 0.0.0, because the Authoring API SPECTACULAR_SETTINGS lives in cms/envs/devstack.py and production.py rather than common.py.
Sorry, something went wrong.
Reviewers
At least 1 approving review is required to merge this pull request.
Add GH workflow to automatically generate openapi schema whenever view file tagged with the "openedx-platform-sdk" @extend_schema tag changes.
Related PR: edly-io/openedx-platform-sdk#1