Python构建RESTful网络服务[Django篇：生成API文档]

系列文章介绍

本系列文章将详细介绍将Django官方引导教程中的投票项目改写为RESTful网络服务。

前置步骤

Step-1：RESTful与Django
Step-2：创建项目和应用
Step-3：使用原生Django编写API
Step-4：序列化与反序列化
Step-5：基于DRF的视图类的视图
Step-6：基于DRF的视图集的视图
Step-7：用户接入控制

前置步骤文章见文末列表。

Step-8：生成API文档

内容提要

使用django-rest-swagger生成API文档
使用coreapi生成API文档

在前后端配合开发中，上游须要制定开发文档，供下游人员使用。一般而言，上游为后端开发者，下游为前端或其他端开发者。而API的制定、更新、共享，靠纯手工显然是难以接受的，在开活动中，很容易产生扯皮、等待等问题。所以我们须要自动化地生成文档。

使用django-rest-swagger生成API文档

安装django-rest-swagger

$ pip install django-rest-swagger

在settings.py中添加相关第三方应用

# in settings.py

# Application definition

REST_FRAMEWORK_APPS = [
    'rest_framework',  #
    'rest_framework.authtoken',  # 认证应用

    'rest_framework_swagger',  # API文档应用 ==>用于生成文档的应用
]

CUSTOM_APPS = [
    ... ...
]

INSTALLED_APPS = [
    ... ...
]\
                 + REST_FRAMEWORK_APPS\
                 + CUSTOM_APPS

配置url分发，

# in pollsapi.py

from django.contrib import admin
from django.urls import path, include

from rest_framework_swagger.views import get_swagger_view


urlpatterns = [
    path('admin/', admin.site.urls),

    path('api-polls/', include('polls.urls')),
    path('api-user-access-control/', include('useraccesscontrol.urls')),

    path('swagger-docs/', get_swagger_view(title='Polls API')),
]

现在，可以启动开发服务器，查看API文档页面了。注意，由于有些API我们设置了认证和权限，所以须要登录查看，可以在页面中按须登录。

使用django-rest-swagger生成API文档

安装django-rest-swagger

$ pip install coreapi

coreapi不须要在settings.py中添加相关第三方应用。

配置url分发，

扫描二维码关注公众号，回复： 5794733 查看本文章

# in pollsapi.py

from django.contrib import admin
from django.urls import path, include

from rest_framework_swagger.views import get_swagger_view
from rest_framework.documentation import include_docs_urls


urlpatterns = [
    path('admin/', admin.site.urls),

    path('api-polls/', include('polls.urls')),
    path('api-user-access-control/', include('useraccesscontrol.urls')),

    path('swagger-docs/', get_swagger_view(title='Polls API')),
    path('docs/', include_docs_urls(title='Polls API', authentication_classes=[], permission_classes=[])),
]

现在，可以启动开发服务器，查看API文档页面了。注意，我们使用authentication_classes=[], permission_classes=[]豁免了认证和权限。

补遗

项目中使用的数据库为PostgreSQL，Django默认的是SQLite3，settings.py中配置如下：

# in settings.py

# Database
# https://docs.djangoproject.com/en/2.1/ref/settings/#databases

# 使用SQLite3
# DATABASES = {
#     'default': {
#         'ENGINE': 'django.db.backends.sqlite3',
#         'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
#     }
# }

# 使用PostgreSQL
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'django_rest',
        'USER': 'webdev',
        'PASSWORD': '5411',
        'HOST': '127.0.0.1',
        'PORT': '5432'
    }
}