OpenAPI schema omits request/response bodies for 32 DRF views missing serializer_class
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 35/100
- issue の種類
- バグ
- 明瞭さ
- おおむね明確
- 活発さ
- 活発
調査の方向性
Start by reproducing with a request to /api-docs/schema/ and grepping the logs for "should either include a .serializer_class". The affected views are in lms/djangoapps/teams/views.py (TopicListView), lms/djangoapps/ora_staff_grader/views.py (where StaffGraderBaseView is the shared source for eight subclasses), and the other files listed in the issue. Done means each listed view gets a body in the generated schema and the assertion no longer appears in the logs. The fix approach is not yet agreed, so confirm it with maintainers before editing.
索引モデルが issue の本文から書いたものです。
説明
Summary
32 DRF views in this repository subclass GenericAPIView (or a concrete generic such as ListAPIView / RetrieveAPIView / UpdateAPIView) but never declare a serializer_class or override get_serializer_class(). During /api-docs/ schema generation, drf-spectacular tries to resolve each view's serializer, DRF raises AssertionError, and drf-spectacular catches it and skips the body schema for that operation.
The endpoints still appear in the schema, but with no documented request or response shape.
Impact
- Published OpenAPI schema documents these operations as
description: No response body, so generated clients and SDKs get no model for them. This matters more than it might seem, since the schema feeds the generated platform SDK (SDK_TAGinopenedx/core/apidocs.py, built by.github/workflows/generate_openapi_schemas.yml). - Secondary, and mostly a local-development cost: each schema generation logs 39 error lines for this (32 from this repo, the rest from dependencies). In production that is bounded by OPENAPI_CACHE_TIMEOUT
, which defaults to one hour inopenedx/envs/common.py. In dev settings the timeout is0, so every request to/api-docs/schema/` regenerates and re-logs the whole set. For scale, one generation emits roughly 1400 drf-spectacular lines in total, so this is a small share of the overall output rather than the main source of it.
Functionality is unaffected; this is a documentation-accuracy problem.
Steps to reproduce
-
Start the LMS (Tutor dev or any devstack).
-
Request the schema so generation runs:
curl -s -o /tmp/schema.yaml http://localhost:8000/api-docs/schema/ -
Inspect the LMS logs:
docker logs <lms-container> 2>&1 | grep "should either include a .serializer_class"
Each affected view logs:
lms/djangoapps/teams/views.py: Error [TopicListView]: exception raised while getting serializer. Hint: Is get_serializer_class() returning None or is get_queryset() not working without a request? Ignoring the view for now. (Exception: 'TopicListView' should either include a `serializer_class` attribute, or override the `get_serializer_class()` method.)
And the resulting schema entry carries no body:
/api/team/v0/topics/
get:
description: GET /api/team/v0/topics/?course_id={course_id}
operationId: api_team_v0_topics_retrieve
responses:
'200':
description: No response body
Affected views
Grouped by file, as reported by drf-spectacular during a full /api-docs/schema/ generation:
common/djangoapps/entitlements/rest_api/v1/views.pyEntitlementEnrollmentViewSet
lms/djangoapps/course_api/blocks/views.pyBlockMetadataViewBlocksInCourseViewBlocksView
lms/djangoapps/grades/rest_api/v1/gradebook_views.pyCourseGradingView
lms/djangoapps/grades/rest_api/v1/views.pyCourseGradingPolicy
lms/djangoapps/learner_home/mock/mock_views.pyInitializeView
lms/djangoapps/mobile_api/course_info/views.pyBlocksInfoInCourseViewCourseHandoutsListCourseUpdatesList
lms/djangoapps/ora_staff_grader/mock/views.pyInitializeViewSubmissionFetchViewSubmissionStatusFetchViewUpdateGradeView
lms/djangoapps/ora_staff_grader/views.pyAssessmentFeedbackViewInitializeViewSubmissionBatchUnlockViewSubmissionFetchViewSubmissionFilesFetchViewSubmissionLockViewSubmissionStatusFetchViewUpdateGradeView
lms/djangoapps/support/views/enrollments.pyEnrollmentSupportListView
lms/djangoapps/support/views/feature_based_enrollments.pyFeatureBasedEnrollmentSupportAPIView
lms/djangoapps/support/views/manage_user.pyManageUserDetailView
lms/djangoapps/support/views/onboarding_status.pyOnboardingView
lms/djangoapps/support/views/sso_records.pySsoView
lms/djangoapps/teams/views.pyMembershipBulkManagementViewTeamsAssignmentsViewTeamsDashboardViewTopicListView
openedx/core/djangoapps/notifications/views.pyMarkNotificationsSeenAPIView
In the ora_staff_grader case the shared base class StaffGraderBaseView is the actual source, so the eight subclasses would be fixed together.
A further 16 views in installed dependencies (completion_aggregator, enterprise, integrated_channels, channel_integrations, lti_consumer) hit the same assertion but need fixing in their own repositories, so they are out of scope here.
Suggested direction
The common shape is a view that inherits a generic base for convenience but implements a plain get() / post() and never uses a serializer. Options per view:
- Subclass
APIViewinstead, where no serializer or queryset is actually used. - Declare
serializer_class, or overrideget_serializer_class(), where a serializer
already exists but was never wired up. - Annotate with
@extend_schema/@extend_schema_viewwhere the response is assembled
by hand and no serializer is appropriate.
Happy to open a PR if maintainers can confirm the preferred approach, and whether they want it split per-app rather than as one sweep.
Related but separate
A larger set of plain APIView-based views logs a different message during the same run (unable to guess serializer. This is graceful fallback handling for APIViews...). That is a distinct, lower-severity gap and is not covered by this report.
Environment
openedx/openedx-platformat commitd9aaee456069cc0a8cf9f2d21ea646ddffbe9ae9- drf-spectacular 0.30.0
- djangorestframework 3.17.2
- Python 3.12, Tutor dev
- 主要言語
- Python
- スター
- 8.2k
- フォーク
- 4.4k
- 平均マージ
- 2日 10時間
- マージ済み PR(30日)
- 40
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
openedx/openedx-platform のほかの issue
-
Discussion API: missing thread returns 500 (ForumV2RequestError not mapped to ThreadNotFoundError)再び着手できるかも @mbhavu2007-lang が 17 日前に担当しましたが、オープン中のプルリクエストはありません。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
openedx/openedx-platform#39225 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
v3 notification preferences: PUT with email_cadence but no notification_channel raises KeyError (500)再び着手できるかも このイシューのプルリクエストはマージされずにクローズされました。 オープンbug
難易度 2/5 1〜3時間 初心者へのやさしさ 66/100
openedx/openedx-platform#39221 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 86/100
openedx/openedx-platform#39169 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
openedx/openedx-platform#39084 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1時間未満 初心者へのやさしさ 82/100
openedx/openedx-platform#38792 ·
メンテナーはふだん 1 日以内に返信
openedx/openedx-platform の issue をすべて見る
似ている issue
-
area: ci bug good first issue help wanted
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
hffgzktbcc-blip/ounce-core#484 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 66/100
ranxianglei/billion-context#7063 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 65/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
-
needs-triage
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
MakazhanAlpamys/Soup#2971 ·
メンテナーはふだん 1 日以内に返信