使用 Django Rest Framework 3.5 自動(dòng)生成 API 文檔
Auto-Generate Swagger Docs for your Django API

3.5新特性：

• Docstrings on your API's views are now included in your schema's definition.
• The helper method get_schema_view() has been added.
• The schema generation code has been fully documented and outlined here.

Django Rest Framework 3.5 附帶了get_schema_view方法，這個(gè)方法會(huì)為你的模式生成Django視圖，它還允許我們傳入一個(gè)Renderer（渲染器）類(lèi)，渲染器將??告訴視圖應(yīng)該如何渲染。舉個(gè)例子：

from rest_framework.schemas import get_schema_view

from rest_framework.renderers import CoreJSONRenderer

schema_view = get_schema_view(
    title='A Different API',
    renderer_classes=[CoreJSONRenderer]
)

將會(huì)渲染你的api生成模式為JSON（具體來(lái)說(shuō)，是遵循CoreAPI規(guī)范的JSON）
現(xiàn)在，使用django-rest-swagger中現(xiàn)成的渲染器，從我們的API生成swagger文檔非常的簡(jiǎn)單。django-rest-swagger提供了兩個(gè)有用的渲染器：SwaggerUIRenderer 和 OpenAPIRenderer。我們兩個(gè)都用，因?yàn)镾waggerUIRenderer實(shí)際上使用渲染的OpenAPI格式。
讓我們嘗試下實(shí)現(xiàn)簡(jiǎn)單的api接口和自動(dòng)生成文檔：

bash/cmd 命令行操作

# 安裝包并構(gòu)建一個(gè)django項(xiàng)目，最后創(chuàng)建管理員
pip install Django
pip install djangorestframework
pip install django-rest-swagger
django-admin startproject api
cd api
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser

api/settings.py 配置文件修改

# 在配置文件中修改兩項(xiàng)設(shè)置
INSTALLED_APPS = [
    # [django core apps]
     ... # 保留之前的apps
    'rest_framework',
    'rest_framework_swagger',
]
...
REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
    ]
}

api/urls.py 生成API

# 為了簡(jiǎn)單，我們直接利用Django自身的基本用戶(hù)模型生成api接口
from django.conf.urls import url, include
from django.contrib.auth.models import User
from rest_framework import routers, serializers, viewsets

# Serializers define the API representation.
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ('url', 'username', 'email', 'is_staff')

# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

# Routers provide an easy way of automatically determining the URL conf.
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)

# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
    url(r'^api/', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

到此處，運(yùn)行項(xiàng)目后 http://localhost:8000/api/users/ 的效果如下圖，登錄后可以 add, create 和 delete。下一步就是生成API的swagger文檔關(guān)鍵步了，它顯得非常簡(jiǎn)潔。

api/urls.py 添加get_schema_view輔助函數(shù)

# existing imports
...
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer

# existing serializer, viewset, router registrations code
...

# Create our schema's view w/ the get_schema_view() helper method. Pass in the proper Renderers for swagger
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

# Inlcude the schema view in our urls.
urlpatterns = [
    url(r'^docs/', schema_view, name="docs"),
    url(r'^api/', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

bash/cmd 運(yùn)行項(xiàng)目

python manage.py runserver

在項(xiàng)目主目錄運(yùn)行該命令，然后在瀏覽器打開(kāi)
http://localhost:8000/docs/
嘗試點(diǎn)擊List Operations和Expand Operations，這用起來(lái)很酷。我們得到了數(shù)據(jù)模型api的操作列表，使用樣例，甚至可以直接在界面中填充表單來(lái)使用這些api。

此外，Django Rest Framework 3.5 使得我們?cè)诓僮髋赃吿砑犹崾咀兊脴O為容易，只需要在類(lèi)的文檔字符串中對(duì)應(yīng)合適的方法名稱(chēng)添加你想要的文字就行了。

# imports and UserSerializer
...
class UserViewSet(viewsets.ModelViewSet):
    """
    retrieve:
        Return a user instance.

    list:
        Return all users, ordered by most recently joined.

    create:
        Create a new user.

    delete:
        Remove an existing user.

    partial_update:
        Update one or more fields on an existing user.

    update:
        Update a user.
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer

# routing
...

最終的api/urls.py

# 為了簡(jiǎn)單，我們直接利用Django自身的基本用戶(hù)模型生成api接口
# just inline a simple api endpoint at 'users/' that exposes Django's base User model
from django.conf.urls import url, include
from django.contrib.auth.models import User
from rest_framework import routers, serializers, viewsets
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer

from django.contrib import admin

# Serializers define the API representation.
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ('url', 'username', 'email', 'is_staff')

# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
    """
    retrieve:
        Return a user instance.

    list:
        Return all users, ordered by most recently joined.

    create:
        Create a new user.

    delete:
        Remove an existing user.

    partial_update:
        Update one or more fields on an existing user.

    update:
        Update a user.
    """

    queryset = User.objects.all()
    serializer_class = UserSerializer

# Routers provide an easy way of automatically determining the URL conf.
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)

# Create our schema's view w/ the get_schema_view() helper method. Pass in the proper Renderers for swagger
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
    url(r'^docs/', schema_view, name="docs"),
    url(r'^api/', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    url(r'^admin/', admin.site.urls),
]