Django REST Swagger是一个强大的工具，它允许开发者通过Swagger UI展示Django REST框架API的交互式文档。Swagger UI是一个用户友好的界面，可以帮助开发者理解和测试API，而无需编写任何额外的代码。本文将深入探讨如何在Django REST Swagger中指定API参数，以便在文档中清晰地呈现API的各个方面。
API参数的种类包括：
1. **Query参数**：附加在URL末尾，以问号分隔，如/users?role=admin。
2. **Path参数**：嵌入URL路径中，如/users/{id}，其中{id}是动态部分。
3. **Header参数**：作为HTTP请求头的一部分，例如X-MyHeader: Value。
4. **Body参数**：用于POST、PUT、PATCH请求的主体内容。
5. **Form参数**：描述Content-Type为application/x-www-form-urlencoded或multipart/form-data的请求数据。
在Django REST Swagger早期版本中，可以使用YAML格式的文档字符串（DocStrings）在视图函数中直接指定API参数。例如：
```python
def cancel(self, request, id):
"""
desc: 取消任务，进行中的参与者得到报酬
ret: msg
err: 404页面/msg
input:
- name: id
desc: 任务id
type: string
required: true
location: path
"""
```
然而，在Django REST Swagger 2.0及更高版本中，不再支持这种YAML文档字符串。为了解决这个问题，可以采取以下策略：
### 解决方案一：使用Django Filters
在Django REST framework的基于类的API视图中，可以定义`filter_class`来过滤模型的特定字段。这将使Swagger根据这些字段自动生成文档。例如：
```python
from django_filters.rest_framework import FilterSet
from .models import Product
class ProductFilter(FilterSet):
class Meta:
model = Product
fields = ('name', 'category', 'id')
class PurchasedProductsList(generics.ListAPIView):
model = Product
serializer_class = ProductSerializer
filter_class = ProductFilter
def get_queryset(self):
user = self.request.user
return user.purchase_set.all()
```
这种方法适用于基于模型的API，但可能无法处理与模型字段不一致的API参数。
### 解决方案二：自定义SchemaGenerator
Django REST Swagger的高级用法中提到了基于类的文档API视图，你可以创建一个自定义视图来生成和返回Swagger schema。例如：
```python
from rest_framework.response import Response
from rest_framework.schemas import SchemaGenerator
from rest_framework.views import APIView
from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
class SwaggerSchemaView(APIView):
permission_classes = [AllowAny]
renderer_classes = [OpenAPIRenderer, SwaggerUIRenderer]
def get(self, request):
generator = SchemaGenerator()
schema = generator.get_schema(request=request)
return Response(schema)
```
这种方法允许你自定义SchemaGenerator，以适应不同类型的API参数，包括那些不直接关联到模型字段的参数。
### 面向类的视图中的参数指定
对于面向类的视图，你可以通过覆盖`get_serializer`或`get_serializer_class`方法来指定序列化器，从而控制API参数的描述。例如：
```python
class CustomView(generics.CreateAPIView):
serializer_class = CustomSerializer
def get_serializer_class(self):
if self.request.method == 'GET':
return CustomGetSerializer
else:
return super().get_serializer_class()
```
在这种情况下，`CustomGetSerializer`和`CustomSerializer`可以分别定义GET和POST请求所需的参数。
### 结论
指定Django REST Swagger的API参数需要理解不同的参数类型，并根据Django REST Swagger版本选择合适的策略。在新版本中，可能需要利用Django Filters、自定义SchemaGenerator或者调整视图和序列化器来实现API参数的详细描述。这样，开发者不仅可以为其他团队成员提供清晰的API文档，还可以方便地通过Swagger UI进行测试和调试。
