如何让swagger_auto_schema识别APIView的请求体参数

现有编写完成的DRF APIView类视图代码如下：

from rest_framework.views import APIView
from rest_framework.response import Response
from drf_yasg.utils import swagger_auto_schema

class SimulationGenerator(APIView):

    @swagger_auto_schema()
    def post(self, request) -> Response:
        """create a simulation"""
        simulation_id = request.data["simulation_id"]
        create_simulation(simulation_id)
        return Response(status=200, data=f"Job with simu_id : {simulation_id} created")

对应URL路由配置：

from django.urls import path

from .views import SimulationGenerator

urlpatterns = [
    path("simulation/", SimulationGenerator.as_view()),
]

该接口调用方式为：向simulation/路径发送POST请求，携带JSON格式请求体：

{ 
     "simulation_id" : "foo"
}

访问生成的Swagger文档时，发现该POST接口的parameters参数列表为空，对应文档片段如下：

"post": {
    "parameters": [],

需要如何配置，才能让swagger_auto_schema正确识别接口需要传入的simulation_id请求参数？

drf_yasg不会自动扫描视图代码里从request.data读取的字段生成接口文档，必须显式给swagger_auto_schema装饰器传入请求体定义，才能让Swagger展示对应的参数，常用的配置方式有两种：

• 轻量内联配置：适合参数少、逻辑简单的接口
  先导入drf_yasg的openapi类型，在装饰器的request_body参数里直接定义请求体结构：

  from drf_yasg import openapi
  
  class SimulationGenerator(APIView):
      @swagger_auto_schema(
          request_body=openapi.Schema(
              type=openapi.TYPE_OBJECT,
              required=['simulation_id'],
              properties={
                  'simulation_id': openapi.Schema(
                      type=openapi.TYPE_STRING,
                      description='仿真任务ID'
                  )
              }
          )
      )
      def post(self, request) -> Response:
          """create a simulation"""
          simulation_id = request.data["simulation_id"]
          create_simulation(simulation_id)
          return Response(status=200, data=f"Job with simu_id : {simulation_id} created")
  

• 序列化器配置：适合参数多、需要参数校验的场景，也是DRF项目的推荐写法
  先定义对应接口的序列化器，一方面给drf-yasg生成文档用，另一方面可以直接复用做请求参数校验，不用手动判断字段是否存在、格式是否正确：

  from rest_framework import serializers
  
  class SimulationCreateSerializer(serializers.Serializer):
      simulation_id = serializers.CharField(required=True, help_text="仿真任务ID")
  

  把序列化器传入装饰器的request_body参数即可：

  class SimulationGenerator(APIView):
      @swagger_auto_schema(request_body=SimulationCreateSerializer)
      def post(self, request) -> Response:
          """create a simulation"""
          serializer = SimulationCreateSerializer(data=request.data)
          serializer.is_valid(raise_exception=True)
          simulation_id = serializer.validated_data["simulation_id"]
          create_simulation(simulation_id)
          return Response(status=200, data=f"Job with simu_id : {simulation_id} created")
  

补充说明：按照OpenAPI规范，POST请求的JSON请求体参数不会放在parameters数组下，而是会放在独立的requestBody字段中。配置完成后刷新文档，就能在接口的请求体参数说明里看到simulation_id字段，同时文档会自动生成对应的请求示例。

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