Django自动生成Swagger接口文档

1. 前言

当接口开发完成，紧接着需要编写接口文档。传统的接口文档通常都是使用Word或者一些接口文档管理平台进行编写，但此类接口文档维护更新比较麻烦，每次接口有变更，需要手动修改接口文档。

在实际的工作中，经常会遇到：“前端抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新”。

为了解决这个问题，业界推出了一个Swagger框架来管理接口文档，实现接口文档的自动更新。

采用Swagger框架来管理接口文档，常用于在微服务架构设计或者Java的后端服务工程中。这也造成了很多人误认为Swagger只是Java语言下的一个框架，其实并不是的，Swagger除了能应用在Java语言的工程中，也同时适用于在其它语言下，比如Python。接下来，在本篇文章，介绍的就是基于Python3+Django3下，如何接入Swagger框架，并且实现Swagger接口文档的自动生成。

2. Swagger介绍

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

image.png

例如：接口测试站点(http://httpbin.org/#/)，也是利用Swagger来生成接口文档的。

Swagger优势：

1)Swagger可生成一个具有互动性的API控制台，开发者可快速学习和尝试API

2)Swagger支持不同客户端SDK代码，用于不同平台上(Java、Python、...)的实现

3)Swagger可在不同的平台上从代码注释中自动生成

4)Swagger社区活跃，里面有许多强悍的贡献者

3. Django项目配置

1、在开始之前，我们先创建一个项目操作目录和隔离环境，具体操作如下：

# 创建项目目录

mkdir django_swagger

cd django_swagger

# 创建隔离开发环境

python3 -m venv env

source env/bin/activate

2、安装django相关库

(env) ➜ pip install django

(env) ➜ pip install djangorestframework

3、创建django项目和app

# 创建django项目和app

django-admin startproject drf_swagger

cd drf_swagger

django-admin startapp api

需要注意的是，本篇文章示例，是基于Python3及Django当前最新库来进行的。

(env) ➜ pip list | grep django

Django 3.0.1

django-crispy-forms 1.8.1

django-formtools 2.2

django-import-export 2.0

django-reversion 3.0.5

djangorestframework 3.11.0

到此，我们已经准备好了django基础环境和生成好了项目结构。

4. Django接入Swagger

网上很多资料在介绍Django接入Swagger方法时，都是基于django-rest-swagger库进行讲解的，都殊不知，从2019年6月份开始，官方已经废弃了该库，在django 3.0中已经不支持该库了，取而代之的是全新的第三方drf-yasg库。

GitHub地址：

https://github.com/marcgibbons/django-rest-swagger

所以本文也是基于drf-yasg库来实现在Django3中接入Swagger框架的。

1、安装drf-yasg库

pip install -U drf-yasg

GitHub项目地址：

https://github.com/axnsan12/drf-yasg

2、修改项目settings.py文件，添加api和drf_yasg。

# Application definition

INSTALLED_APPS = [

'django.contrib.admin',

'django.contrib.auth',

'django.contrib.contenttypes',

'django.contrib.sessions',

'django.contrib.messages',

'django.contrib.staticfiles',

'rest_framework',

'drf_yasg',

'api',

]

3、修改api/models.py，此处定义了一个添加接口的model模型(为了方便演示)

ffrom django.db import models

class APIInfo(models.Model):

api_name = models.CharField(max_length=32, verbose_name="接口名称", default="请输入接口名称")

# 接口描述

api_describe = models.TextField(max_length=255, verbose_name="接口描述", default="请输入接口描述")

# 接口负责人

api_manager = models.CharField(max_length=11, verbose_name="接口负责人", default="请输入接口负责人名字")

# 创建时间

create_time = models.DateTimeField(auto_now_add=True, verbose_name="创建时间")

# 修改时间

update_time = models.DateTimeField(auto_now=True, blank=True, null=True, verbose_name="修改时间")

class Meta:

db_table = 'api_info'

# 设置表名，默认表名是：应用名称_模型类名

# 带有应用名的表名太长了

verbose_name = '接口列表'

verbose_name_plural = "接口列表"

def __str__(self):

return self.api_name

4、修改api/admin.py，将model注册到后台，方便在管理后台添加接口记录。

from django.contrib import admin

from . models import APIInfo

admin.site.register(APIInfo)

5、新建api/serializers.py文件，代码内容如下:

from rest_framework import serializers

from api.models import APIInfo

class APIInfoSerializer(serializers.HyperlinkedModelSerializer):

class Meta:

model = APIInfo

fields = "__all__"

class APISerializer(serializers.ModelSerializer):

class Meta:

model = APIInfo

fields = "__all__"

6、修改api/view.py视图文件，并在类中，添加注释如下所示(为了方便演示)：

from rest_framework import viewsets

from rest_framework import generics

from . import models

from . import serializers

class APIList(generics.ListAPIView):

"""

查看接口列表

"""

queryset = models.APIInfo.objects.all()

serializer_class = serializers.APISerializer

class APIDetail(generics.RetrieveAPIView):

"""

查看接口详细

"""

queryset = models.APIInfo.objects.all()

serializer_class = serializers.APISerializer

class APIDetail(generics.RetrieveUpdateDestroyAPIView):

"""

更新接口内容

"""

queryset = models.APIInfo.objects.all()

serializer_class = serializers.APISerializer

class APIInfoViewSet(viewsets.ModelViewSet):

"""

retrieve:

返回一组(查)

list:

返回所有组(查)

create:

创建新组(增)

delete:

删除现有的一组(删)

partial_update:

更新现有组中的一个或多个字段(改：部分更改)

update:

更新一组(改：全部更改)

"""

queryset = models.APIInfo.objects.all()

serializer_class = serializers.APIInfoSerializer

7、修改api/urls.py文件，进行路由配置。

from django.conf.urls import url

from . import views

urlpatterns = [

url('', views.APIList.as_view()),

url('/', views.APIDetail.as_view()),

]

8、修改项目urls.py文件，进行路由配置。

from django.conf.urls import url

from django.contrib import admin

from django.conf import settings

from django.conf.urls import include

from rest_framework import routers, permissions

from drf_yasg.views import get_schema_view

from drf_yasg import openapi

from api import views

router = routers.DefaultRouter()

router.register('api_info', views.APIInfoViewSet)

schema_view = get_schema_view(

openapi.Info(

title="测试工程API",

default_version='v1.0',

description="测试工程接口文档",

terms_of_service="#",

contact=openapi.Contact(email="测试"),

license=openapi.License(name="BSD License"),

),

public=True,

permission_classes=(permissions.AllowAny,),

)

urlpatterns = [

url('admin/', admin.site.urls),

# 配置django-rest-framwork API路由

url('api/', include('api.urls')),

url('api-auth/', include('rest_framework.urls', namespace='rest_framework')),

# 配置drf-yasg路由

url('^swagger(?P\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),

url('swagger', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),

url('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),

]

5. 执行数据同步、运行

1、上述一切配置完成后，开始进行数据库迁移、同步。

# 生成迁文件、执行同步

python manage.py makemigrations

python manage.py migrate

2、创建后台管理员用户

python manage.py createsuperuser

3、运行服务

python manage.py runserver

6. 验证效果

1、服务运行起来后，默认端口为8000，浏览器访问http://127.0.0.1:8000/redoc/，可查看redoc ui，效果如下所示。

2、点击左侧的api，展开各接口详细如下所示。

PS: ReDoc 是另一个 Swagger UI 工具。

3、继续访问http://127.0.0.1:8000/swagger，即可看到日常我们熟悉的Swagger接口文档界面了。

4、Swagger除了可以即时生成接口文档以外，还可以用于在线做一些接口功能测试，如下所示。

5、在Swagger中还可以查看到在model定义的各字段类型及参数说明。

到此，我们Django3接入Swagger已经完成了