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的主要用法并对接口文档的设计有更深入的了解。
