OpenAPI schema omits request/response bodies for 32 DRF views missing serializer_class

Đang mở
#39,319 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

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
Công nghệ
django, openapi, python
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_TAG in openedx/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 in openedx/envs/common.py. In dev settings the timeout is 0, 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

  1. Start the LMS (Tutor dev or any devstack).

  2. Request the schema so generation runs:

    curl -s -o /tmp/schema.yaml http://localhost:8000/api-docs/schema/
    
  3. 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.py
    • EntitlementEnrollmentViewSet
  • lms/djangoapps/course_api/blocks/views.py
    • BlockMetadataView
    • BlocksInCourseView
    • BlocksView
  • lms/djangoapps/grades/rest_api/v1/gradebook_views.py
    • CourseGradingView
  • lms/djangoapps/grades/rest_api/v1/views.py
    • CourseGradingPolicy
  • lms/djangoapps/learner_home/mock/mock_views.py
    • InitializeView
  • lms/djangoapps/mobile_api/course_info/views.py
    • BlocksInfoInCourseView
    • CourseHandoutsList
    • CourseUpdatesList
  • lms/djangoapps/ora_staff_grader/mock/views.py
    • InitializeView
    • SubmissionFetchView
    • SubmissionStatusFetchView
    • UpdateGradeView
  • lms/djangoapps/ora_staff_grader/views.py
    • AssessmentFeedbackView
    • InitializeView
    • SubmissionBatchUnlockView
    • SubmissionFetchView
    • SubmissionFilesFetchView
    • SubmissionLockView
    • SubmissionStatusFetchView
    • UpdateGradeView
  • lms/djangoapps/support/views/enrollments.py
    • EnrollmentSupportListView
  • lms/djangoapps/support/views/feature_based_enrollments.py
    • FeatureBasedEnrollmentSupportAPIView
  • lms/djangoapps/support/views/manage_user.py
    • ManageUserDetailView
  • lms/djangoapps/support/views/onboarding_status.py
    • OnboardingView
  • lms/djangoapps/support/views/sso_records.py
    • SsoView
  • lms/djangoapps/teams/views.py
    • MembershipBulkManagementView
    • TeamsAssignmentsView
    • TeamsDashboardView
    • TopicListView
  • openedx/core/djangoapps/notifications/views.py
    • MarkNotificationsSeenAPIView

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 APIView instead, where no serializer or queryset is actually used.
  • Declare serializer_class, or override get_serializer_class(), where a serializer
    already exists but was never wired up.
  • Annotate with @extend_schema / @extend_schema_view where 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-platform at commit d9aaee456069cc0a8cf9f2d21ea646ddffbe9ae9
  • 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

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. 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.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của openedx/openedx-platform

Tất cả issue của openedx/openedx-platform

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.