OpenAPI schema omits request/response bodies for 32 DRF views missing serializer_class
Maintainer thường phản hồi trong vòng 1 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức phù hợp với người mới
- 35/100
- Loại issue
- Lỗi
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Sôi nổi
- Lĩnh vực
- api, backend-api-design
Hướng nghiên cứu
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.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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
- Ngôn ngữ chính
- Python
- Star
- 8.2k
- Fork
- 4.4k
- Merge trung bình
- 2 ngày 10 giờ
- Pull request đã merge (30 ngày)
- 40
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của openedx/openedx-platform
-
Discussion API: missing thread returns 500 (ForumV2RequestError not mapped to ThreadNotFoundError)Có thể làm lại được @mbhavu2007-lang đã nhận 17 ngày trước và không có pull request nào đang mở. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
openedx/openedx-platform#39225 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
v3 notification preferences: PUT with email_cadence but no notification_channel raises KeyError (500)Có thể làm lại được Pull request cho issue này đã bị đóng mà không được merge. Đang mởbug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 66/100
openedx/openedx-platform#39221 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 86/100
openedx/openedx-platform#39169 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
openedx/openedx-platform#39084 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 Dưới một giờ Mức phù hợp với người mới 82/100
openedx/openedx-platform#38792 ·
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của openedx/openedx-platform
Issue tương tự
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 77/100
canonical/paas-charm#407 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 5 ngày
-
bug
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 90/100
FAIRmat-NFDI/pynxtools-spm#136 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
enhancement tooling
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 84/100
Maintainer thường phản hồi trong vòng 1 ngày
-
`read_nexus` entry point points to a function that no longer existsCó thể đã có người làm @RubelMozumder đã nhận hôm nay. Đang mởannotator bug
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 88/100
FAIRmat-NFDI/pynxtools#876 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
[Bug]: HTTP 499 (Client Closed Request) is classified as a non-retryable format_error, so a mid-flight abort fails the turn over instead of retryingCó thể đã có người làm @yipinghuang1991 đã nhận hôm nay. Đang mởcomp/agent P2 type/bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
NousResearch/hermes-agent#156837 ·
Maintainer thường phản hồi trong vòng 1 ngày