Bob's Blog

经过前面的步骤，我们现在已经有了关于project的api，以后还会添加更多的api，那么接口文档就需要准备好，特别在有前后端分工的情况，这样其他人能知道目前已有的api以及支持的方法。

我们可以先把project相关的接口文档做出来，这样在之后就形成了习惯，不用最后再来添加。打算用类似127.0.0.1:8000/api/docs/的地址来展示接口文档。

swagger是一个不错的选择。

安装rest-swagger

pip install django-rest-swagger

在settings.py中INSTALLED_APPS里添加'rest-framework-swagger'。

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

在app里的view.py中添加相应的注释。

from rest_framework import generics


class ProjectList(generics.ListCreateAPIView):
    """
        get:
            Return all projects.

        post:
            Create a new project.
    """
    queryset = Project.objects.all()
    serializer_class = ProjectSerializer


class ProjectDetail(generics.RetrieveUpdateAPIView):
    """
        get:
            Return a project instance.

        put:
            Update a project.

        patch:
            Update one or more fields on an existing project.

    """
    queryset = Project.objects.all()
    serializer_class = ProjectSerializer

在项目url.py中添加get_schema_view和对应的url

from django.contrib import admin
from django.urls import include, path
from rest_framework import routers
from center import views
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer


router = routers.DefaultRouter()

schema_view = get_schema_view(title='API DOC', renderer_classes=[SwaggerUIRenderer, OpenAPIRenderer])  # add

urlpatterns = [
    path('api/', include(router.urls)),
    path('api/projects/', include('projects.urls')),
    path('admin/', admin.site.urls),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    path('api/docs/', schema_view, name='docs')  # add
]

此时运行python manage.py runserver, 便可以在127.0.0.1:8000/api/docs/看到api的对应内容。

如果遇到错误提示：'Expected a `coreapi.Document` instance'，那么可以检查下djangorestframework的版本，我是3.11.0，换成3.9.2就正常了。

此时settings.py中debug为true，当以后正式部署时则会加载不了css,js，这时我们可以先运行python manage.py collect static来收集admin, rest framework, swagger的静态文件，之后用nginx代理来处理静态资源的访问，即使debug为false时也能够正常访问。nginx.conf的配置放之后再说。