Django 自动生成api接口文档教程

下面我将详细讲解“Django 自动生成api接口文档教程”的完整攻略，包括以下主要内容：

1. 安装和配置Django-rest-swagger
2. 编写接口文档注释
3. 在项目中使用Django-rest-swagger生成接口文档

1. 安装和配置Django-rest-swagger

首先，我们需要通过pip安装Django-rest-swagger。在Django的项目根目录下，打开终端或命令行，输入如下指令：

pip install django-rest-swagger

安装成功后，我们需要把rest_framework和rest_framework_swagger两个app添加到我们的项目中，在settings.py文件中添加以下代码：

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

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

这样，我们就完成了Django-rest-swagger的安装和配置。

2. 编写接口文档注释

在我们的Django项目中，我们需要为每个接口编写文档注释，以便Django-rest-swagger能够生成接口文档。文档注释应该包含请求参数、响应参数、参数类型和参数说明等信息。

例如，我们编写一个返回字符串的接口，我们可以在views.py文件的函数中添加注释，格式应该如下：

from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view(['GET'])
def hello(request, name):
    """
    返回指定name的字符串

    ---
    parameters:
        - name: name
          description: name参数说明
          required: true
          type: string
          paramType: path
    """
    return Response('Hello, {}'.format(name))

以上代码中，我们使用@api_view修饰器指定了视图函数hello可以响应GET请求，请求的路径中包含一个参数name。我们在注释中，用参数description指定了name的说明，用参数required指定了name是否是必选参数，用参数type指定了name的类型。

3. 在项目中使用Django-rest-swagger生成接口文档

最后，我们可以通过在urls.py中映射Django-rest-swagger的url，访问自动生成的接口文档。例如，我们在项目的urls.py中添加以下代码：

from django.conf.urls import url
from rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='API 文档')

urlpatterns = [
    # ...
    url(r'^docs/$', schema_view),
    # ...
]

然后，在浏览器中访问http://localhost:8000/docs/，就可以看到自动生成的接口文档了。

除此之外，我们还可以使用Django-rest-swagger提供的一些装饰器，例如@api_view和@swagger_auto_schema来帮助我们更方便地生成接口文档。

如下面这个示例代码所示，其中包括了两条完整示例内容：

from django.shortcuts import render
from rest_framework import status
from rest_framework.decorators import api_view, authentication_classes, permission_classes
from rest_framework.response import Response
from rest_framework.authentication import TokenAuthentication
from rest_framework.permissions import IsAuthenticated
from rest_framework_swagger.views import get_swagger_view
from rest_framework.decorators import renderer_classes
from rest_framework.renderers import JSONRenderer

schema_view = get_swagger_view(title='API')

@api_view(['GET'])
def api_root(request, format=None):
    """
    API Document.

    API 包含如下两个子路径：

    * users - 用户信息
    * blog - 博客内容

    ---
    """
    return Response({
        'users': reverse('users_list', request=request, format=format),
        'blog': reverse('blog_list', request=request, format=format)
    })


# 用户列表
@authentication_classes([TokenAuthentication])
@permission_classes([IsAuthenticated])
@api_view(['GET'])
@renderer_classes([JSONRenderer]) # 指定返回结果为JSON格式
def users_list(request, format=None):
    """
    获取所有用户.

    该API接口返回一个列表，包含了所有用户的信息。

    ---
    """
    users = User.objects.all()
    serializer = UserSerializer(users, many=True)
    return Response(serializer.data)


# 博客列表
@api_view(['GET', 'POST'])
def blog_list(request, format=None):
    """
    博客列表.

    获取博客列表或添加新博客.

    ---
    """
    if request.method == 'GET':
        blogs = Blog.objects.all()
        serializer = BlogSerializer(blogs, many=True)
        return Response(serializer.data)
    elif request.method == 'POST':
        serializer = BlogSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

以上就是“Django 自动生成api接口文档教程”的完整攻略，希望能够对您有所帮助。