EnrollmentRetrieveView is routed at two URL patterns
(openedx/core/djangoapps/enrollments/v2/urls.py):
GET /api/enrollment/v2/enrollment/{username},{course_id}
GET /api/enrollment/v2/enrollment/{course_id}
The @extend_schema on its get() method declares both path parameters, so
on the second route the published schema contains a username path parameter
that the URL template has no placeholder for.
Why it matters
openapi-python-client skips any operation whose declared path parameters
don't match its URL, so GET /v2/enrollment/{course_id} disappears from a
generated client entirely. We work around it in the
openedx-platform-sdk
by stripping the parameter before generation, but the published schema stays
wrong for every other consumer.
Why it isn't a one-liner
OpenAPI can't express "this path parameter exists on one of my routes but not
the other" — a path parameter belongs to the path template, not the view.
required=False isn't valid either; OpenAPI requires path parameters to be
required: true.
drf-spectacular's
recommended fix
is to split the view into two classes sharing a base, each declaring its own
schema. That needs the two enrollment-v2-retrieve URL names and the
has_api_key / staff permission logic untangled across both, so it's a
structural change rather than a schema annotation.
Related
Two schema/response mismatches in the same API are fixed in
#39120. This one is left out
of that PR because it needs the view split above.
EnrollmentRetrieveViewis routed at two URL patterns(
openedx/core/djangoapps/enrollments/v2/urls.py):GET /api/enrollment/v2/enrollment/{username},{course_id}
GET /api/enrollment/v2/enrollment/{course_id}
The
@extend_schemaon itsget()method declares both path parameters, soon the second route the published schema contains a
usernamepath parameterthat the URL template has no placeholder for.
Why it matters
openapi-python-clientskips any operation whose declared path parametersdon't match its URL, so
GET /v2/enrollment/{course_id}disappears from agenerated client entirely. We work around it in the
openedx-platform-sdk
by stripping the parameter before generation, but the published schema stays
wrong for every other consumer.
Why it isn't a one-liner
OpenAPI can't express "this path parameter exists on one of my routes but not
the other" — a path parameter belongs to the path template, not the view.
required=Falseisn't valid either; OpenAPI requires path parameters to berequired: true.drf-spectacular's
recommended fix
is to split the view into two classes sharing a base, each declaring its own
schema. That needs the two
enrollment-v2-retrieveURL names and thehas_api_key/ staff permission logic untangled across both, so it's astructural change rather than a schema annotation.
Related
Two schema/response mismatches in the same API are fixed in
#39120. This one is left out
of that PR because it needs the view split above.