django-rest-framework 系列教程（二）- Generate and read automatic documentation with django-rest-swagger

使用的环境：

• python 2.7.10
• Django 1.8.5
• djangorestframework 3.4.4
• django-rest-swagger 0.3.10

创建项目

startproject rest_api

创建 APP

startapp core

配置 rest_api/settings.py

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'rest_framework_swagger',
    'core',

)

配置 rest_api/urls.py

# -*- coding:utf-8 -*-
from django.conf.urls import url, include

urlpatterns = [
    url(r'^api/', include('core.urls', namespace='core')),
]

创建模型 core/models.py

# -*- coding:utf-8 -*-
from django.db import models


class University(models.Model):
    name = models.CharField(max_length=50)

    class Meta:
        verbose_name = "University"
        verbose_name_plural = "Universities"

    def __unicode__(self):
        return self.name


class Student(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    university = models.ForeignKey(University)

    class Meta:
        verbose_name = "Student"
        verbose_name_plural = "Students"

    def __unicode__(self):
        return '%s %s' % (self.first_name, self.last_name)

序列化 core/serializers.py

# -*- coding:utf-8 -*-
from rest_framework import serializers
from .models import University, Student


class UniversitySerializer(serializers.ModelSerializer):
    class Meta:
        model = University


class StudentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student

视图 core/views.py

# -*- coding:utf-8 -*-
from rest_framework import viewsets
from .models import University, Student
from .serializers import UniversitySerializer, StudentSerializer


class StudentViewSet(viewsets.ModelViewSet):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer


class UniversityViewSet(viewsets.ModelViewSet):
    queryset = University.objects.all()
    serializer_class = UniversitySerializer

路由 core/urls.py

# -*- coding:utf-8 -*-
from django.conf.urls import url, include
from rest_framework import routers
from .views import StudentViewSet, UniversityViewSet

router = routers.DefaultRouter()
router.register(r'students', StudentViewSet)
router.register(r'universities', UniversityViewSet)

urlpatterns = [
    url(r'^docs/', include('rest_framework_swagger.urls')),
]

urlpatterns += router.urls

效果截图

Api Root – Django REST framework

Student List – Django REST framework

University List – Django REST framework

Swagger UI

新版本变更

如果使用的 django-rest-swagger 是最新的版本 2.0.5，那么需要做以下修改：
视图部分 core/views.py

from rest_framework import viewsets
from .models import University, Student
from .serializers import UniversitySerializer, StudentSerializer
from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
from rest_framework.decorators import api_view, renderer_classes
from rest_framework import response, schemas


@api_view()
@renderer_classes([SwaggerUIRenderer, OpenAPIRenderer])
def schema_view(request):
    generator = schemas.SchemaGenerator(title='Core API')
    return response.Response(generator.get_schema(request=request))


class StudentViewSet(viewsets.ModelViewSet):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer


class UniversityViewSet(viewsets.ModelViewSet):
    queryset = University.objects.all()
    serializer_class = UniversitySerializer

路由部分 core/urls.py

from django.conf.urls import url
from rest_framework import routers
from .views import StudentViewSet, UniversityViewSet, schema_view


router = routers.DefaultRouter()
router.register(r'students', StudentViewSet)
router.register(r'universities', UniversityViewSet)

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

urlpatterns += router.urls

最终的效果

Swagger UI