django-rest-swagger的优化使用方法

下面我将为您详细讲解“django-rest-swagger的优化使用方法”的完整攻略:

1. 什么是django-rest-swagger？

django-rest-swagger 是rest_framework 的一个扩展，它可以自动生成 API 的文档页面，让前端和其他开发者更方便的查看和测试 API 接口。

2. 使用django-rest-swagger前的准备工作

安装 django-rest-swagger

pip install django-rest-swagger

在 settings.py 配置 REST_FRAMEWORK 和 SWAGGER_SETTINGS

INSTALLED_APPS += [
    'rest_framework_swagger',
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

SWAGGER_SETTINGS = {
    'USE_SESSION_AUTH': False, # 不使用session验证
    'SECURITY_DEFINITIONS': {
        'Api Token': {
           'type': 'apiKey',
           'name': 'Authorization',
           'in': 'header'
        }
    }
}

3. 使用django-rest-swagger优化API的详细步骤

3.1 使用schema生成文档

在 views.py 中指定 schema 属性为 SwaggerAutoSchema 的实例，这样能使文档更清晰，并生成文档的一些其他特性，例如分组、描述等

示例代码：

from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.permissions import AllowAny
from rest_framework.schemas import ManualSchema
from rest_framework_swagger import renderers
from rest_framework_swagger import serializers
from rest_framework_swagger import viewsets as vs
from rest_framework_swagger import renderers


class BooksViewSet(viewsets.ModelViewSet):
    queryset = Books.objects.all()
    serializer_class = BooksSerializer
    schema = vs.SwaggerAutoSchema(

        operation_id_base='book-demo',
        manual_fields=[
            coreapi.Field('category', required=True, location='query', description='类型')
        ],
        responses={
            '400': "参数错误",
            '401': "没有访问权限，或者AccessToken过期",
            '404': "资源不存在",
            '405': "请求方法错误",
            '500': "服务器错误"
        },

    )

    @action(
        detail=False,
        methods=['get'],
        permission_classes=[AllowAny],
        serializer_class=ser.BookListSerializer,
        renderer_classes=[renderers.JSONRenderer],
   )
    def get_books_from_category(self, request):
        category_name = request.query_params.get("category", "")
        category = Category.objects.get(name=category_name)

        books = Books.objects.filter(category=category)
        serializer = BookListSerializer(books, many=True, context={'request': request})
        return JsonResponse(serializer.data, safe=False)

3.2 使用markdown语法描述API

在API的 docstring 里面（即 views.py 文件里面各个方法的参数说明文字），编写Markdown格式的文档，可以更好的让其他开发者了解API的使用方法和参数信息。

示例代码：

class BooksViewSet(viewsets.ModelViewSet):
    queryset = Books.objects.all()
    serializer_class = BooksSerializer

    def list(self, request):
        """
        获取所有书籍
        ---
        parameters:
            - name: format
              description: 输出格式
              required: false
              type: string
              choices: ['json', 'xml']
              default: json
              location: query

        """
        books = self.get_queryset()
        serializer = self.get_serializer(books, many=True)
        return Response(serializer.data)

4. 示例代码

在此提供一个能够让前端开发者通过API文档请求WebSocket 实时推送服务的示例代码。

import logging
import json
from channels import Group
from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.permissions import AllowAny
from rest_framework.response import Response
from rest_framework_swagger import viewsets as vs

logging.basicConfig()

class NotificationViewSet(viewsets.ViewSet):
    @action(detail=False, methods=['post'], permission_classes=[AllowAny])
    def send_message(self, request):
        """
        发送通知
        ---
        parameters:
            - name: msg
              description: 通知内容
              type: string
              required: true
            - name: uuid
              description: 用户id
              type: string
              required: true

        """
        data = request.data
        group_name = f"notification-{data['uuid']}"
        Group(group_name).send({'text': json.dumps(data)})
        return Response({'code': 200, "msg": "ok"})

这段代码中，我们通过 Channel 包创建了一个 WebSocket 的分组（Group），然后在 Django 中，通过请求 API 的方式向这个 Group 中发送了一条消息，消息的内容是 request.data 中的 msg，接收到该WebSocket消息的客户端便可获取该实时消息。

5. 总结

以上就是django-rest-swagger优化API的方法和示例代码，除了可以对API接口进行清晰的文档描述外，还能通过某些特性（例如分组、描述等）组织文档，使文档更清晰直观。同时， 我们还给出了一个示例代码，用以展示如何配合使用 websocket 实现消息的实时推送功能，希望对您有帮助。