drf-spectacular生成Swagger文档时返回数组而非字典的问题排查

以下是几种可行的解决思路：

• 检查视图基类：如果你的接口是返回单个实例的详情接口，确保使用的是RetrieveAPIView而非ListAPIView。ListAPIView会默认告知drf-spectacular返回集合类型响应，即便你手动指定many=False也可能被覆盖。

• 显式指定响应状态码映射：在@extend_schema中通过字典形式明确绑定状态码与序列化器，避免直接传递序列化器实例导致的推断异常：

  @extend_schema(
      responses={
          200: RespondentResponseTransactionalWithQuestionGetSerializer(many=False)
      }
  )
  def get(self, request, *args, **kwargs):
      # 你的接口逻辑
  

• 验证视图返回值类型：确保视图的get_object（或对应处理方法）返回的是单个模型实例，而非查询集（QuerySet）。如果返回的是查询集，即便只包含一条数据，drf-spectacular仍会识别为数组响应。

• 清除drf-spectacular缓存：缓存的旧 schema 数据可能导致显示异常，执行以下命令清除缓存后重新生成：

  python manage.py spectacular --clear-cache
  

• 排查冲突的视图混入类：如果视图继承了ListModelMixin等集合相关的混入类，且该混入类并非当前接口所需，移除它以避免响应类型被错误推断。

内容的提问来源于stack exchange，提问作者Nikitka Gurtovoy