REST-framework快速构建API--生成Swagger接口文档

一、Swagger概述

1.引言

当接口开发完成，紧接着需要编写接口文档。传统的接口文档使用Word编写，or一些接口文档管理平台进行编写，但此类接口文档维护更新比较麻烦，每次接口有变更，需要手动修改接口文档。为了改善这种情况，推荐使用Swagger来管理接口文档，实现接口文档的自动更新。

2.Swagger简介

Swagger：是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。当接口有变动时，对应的接口文档也会自动更新。

Swagger优势：
1）Swagger可生成一个具有互动性的API控制台，开发者可快速学习和尝试API
2）Swagger可生成客户端SDK代码，用于不同平台上（Java、Python...）的实现
3）Swagger文件可在许多不同的平台上从代码注释中自动生成
4）Swagger有一个强大的社区，里面有许多强悍的贡献者

二、Swagger安装和配置

参考官网：https://github.com/marcgibbons/django-rest-swagger

1.安装django-rest-swagger

pip install django-rest-swagger

2、配置

在INSTALLED_APPS中添加'rest_framework_swagger'

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'app01.apps.App01Config',
    'rest_framework',
    'corsheaders',
    'rest_framework_swagger', #新增
]

3.`views.py`，定义的Model`Viewset的说明`

class MarkdownModelView(viewsets.ModelViewSet):
    '''
                retrieve:
                    Return a markdown instance.

                list:
                    Return all markdown,ordered by most recent joined.

                create:
                    Create a new markdown.

                delete:
                    Remove a existing markdown.

                partial_update:
                    Update one or more fields on a existing markdown.

                update:
                    Update a markdown.
            '''

    authentication_classes = [ ]
    queryset = Markdown.objects.all()
    serializer_class = MarkdownModelSerializers
    pagination_class = StandardResultsSetPagination

4、新增url

修改urls文件，新增如下内容：

from django.conf.urls import url,include

from rest_framework_swagger.views import get_swagger_view
schema_view = get_swagger_view(title='任务管理系统')


url(r'^docs',schema_view)