djangoswagger的全面介绍

Django是一个常用的Python Web框架，而djangoswagger，作为Django的一部分，是一个将Django Rest framework（DRF）API自动生成为Swagger UI和模型类文档的工具，使得API文档化更加方便并可视化。在本文中，我们将分别从以下几个方面详细介绍djangoswagger的特点和用法。

一、安装和配置

安装djangoswagger可以使用pip命令：

pip install django-rest-swagger

紧接着，在你的DRF配置类文件中添加以下应用配置：

INSTALLED_APPS = [
    ...,
    'rest_framework_swagger',
]

启用REST framework的API文档格式化器：

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
        'rest_framework_swagger.renderers.OpenAPIRenderer',
        'rest_framework_swagger.renderers.SwaggerUIRenderer',
    )
}

这样，你的djangoswagger配置就完成了。

二、使用swagger UI

djangoswagger的核心是Swagger UI，它可以方便地展示API文档的结构和参数。对于使用djangoswagger来说，想要在浏览器中显示Swagger UI很简单：

首先在你的Django项目的urls.py文件中添加以下代码段，注意需要导入urls，schema_view和get_swagger_view的声明：

from django.urls import path
from rest_framework_swagger.views import get_swagger_view
from rest_framework_schemas import get_schema_view

schema_view = get_swagger_view(title='API Documents')
urlpatterns = [
    ...,
    path('api-docs/', schema_view),
]

然后，访问 ‘/api-docs/’ URL，就能看到你的API文档了。

三、编写API信息和参数

编写API信息和参数是djangoswagger的一个重要功能，同时也是开发者最需要关注的部分。通过在你的DRF视图类中添加djangoswagger的注解，API文档就能自动生成：

from rest_framework.decorators import api_view, authentication_classes, permission_classes, renderer_classes
from rest_framework.response import Response
from rest_framework.renderers import JSONRenderer
from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
from rest_framework_swagger import renderers
from rest_framework.authentication import BasicAuthentication
from rest_framework.permissions import IsAuthenticated

@api_view(['POST'])
@authentication_classes([BasicAuthentication])
@permission_classes([IsAuthenticated])
@renderer_classes([JSONRenderer, OpenAPIRenderer, SwaggerUIRenderer])
def my_view(request):
    """
    API 接口文档描述
    ---
    请求参数:
        - a: integer // 描述参数1
        - b: string  // 描述参数2
    返回参数：
        - id: integer //返回参数1
        - name: string //返回参数1
    """
    return Response({'message': 'Hello, Django Swagger!'})

通过上述代码我们完成了一个简单的API接口，能够将输入参数a、b返回并输出到接口中。其中注解中的描述信息更加直观地体现了API接口的输入输出参数与详细介绍。djangoswagger能够解析上述注解中的格式，从而自动展示在Swagger UI的API “操作”页面中，方便开发者查看。

四、使用Markdown格式

Swagger UI支持使用Markdown格式，让你不必受限于注解语法的规范，更加自由地书写API接口的详细介绍和示例代码。你可以在注解中标注Markdown格式字符串，以实现多样化的文本效果。

例如，接口简要介绍中我们用到了控制标签的方式，以实现更加清晰的显示效果：

@api_view(['POST'])
@renderer_classes([JSONRenderer, OpenAPIRenderer, SwaggerUIRenderer])
def hello(request):
    """
    ### 访问接口：/Hello/

    * **功能**

        获取Hello信息，主要用于测试访问接口是否正常。

    * **请求参数**

        无

    * **返回参数**

        - `Hello` : string ，返回基本信息

    """
    return Response({'Hello': 'Hello，Django Swagger!'})

五、在方法级别上定义标签

默认情况下，Django Swagger会使用基于视图类的路由实例的支持，自动检测API接口的操作。如果你想在方法级别上定义标签、描述信息等元数据，djangoswagger也允许你这么做：

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    method='post',
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        required=['username', 'password'],
        properties={
            'username': openapi.Schema(type=openapi.TYPE_STRING, description='用户名'),
            'password': openapi.Schema(type=openapi.TYPE_STRING, description='密码')
        }),
    operation_description="注册填写信息"
)
@api_view(['POST'])
def register(request):
    """
    注册
    """
    serializer = UserSerializer(data=request.DATA)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    else:
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

在上述代码中我们添加了一个名叫register的API方法，给它添加了一些元数据，如参数详细介绍、请求方式等。

六、结尾

Django Swagger作为Django的扩展在API文档自动生成方面发挥了很大的作用，使得API文档的编写变得更加灵活和便捷。通过学习本文的介绍和代码示例，我们相信读者能够掌握Django Swagger的主要用法并对接口文档的设计有更深入的了解。