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

オープン
#39,319 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
35/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
活発
技術スタック
django, openapi, python

調査の方向性

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_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
主要言語
Python
スター
8.2k
フォーク
4.4k
平均マージ
2日 10時間
マージ済み PR(30日)
40

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

openedx/openedx-platform のほかの issue

openedx/openedx-platform の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。