python接口文档生成_Django Swagger接口文档生成

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

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

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

4)Swagger有一个强大的社区，里面有许多强悍的贡献者

二、Django接入Swagger

大致步骤

1.安装django-rest-swagger2.进入到setting.py文件，添加django-rest-swagger应用3.进入到views.py，将之前定义的UserViewSet和GroupViewset补充注释4.在urls.py中添加get_schema_view辅助函数5.启动Django服务，检测Swagger接口文档配置效果

环境说明

python 3.7.3Django2.2.4djangorestframework==3.9.2django-rest-swagger 2.2.0

安装模块

pip3 install djangorestframework==3.9.2

注意：djangorestframework版本不能高于3.9.2，否则访问/docs/出现以下错误。

Expected a `coreapi.Document` instance

按照网友的意思，Django Swagger模块已经不维护了，只能支持到3.9.2

另外，django版本不能大于3.x。

配置setting.py

使用Pycharm新建一个项目：t_swagger，app名为api

修改t_swagger/settings.py，增加2行

INSTALLED_APPS =['django.contrib.admin','django.contrib.auth','django.contrib.contenttypes','django.contrib.sessions','django.contrib.messages','django.contrib.staticfiles','api.apps.ApiConfig','rest_framework',

'rest_framework_swagger']

在swagger/settings.py末尾处，增加Swagger配置

# swagger 配置项

SWAGGER_SETTINGS={

# 基础样式'SECURITY_DEFINITIONS': {"basic":{'type': 'basic'}

},

# 如果需要登录才能够查看接口文档, 登录的链接使用restframework自带的.'LOGIN_URL': 'rest_framework:login','LOGOUT_URL': 'rest_framework:logout',

#'DOC_EXPANSION': None,

#'SHOW_REQUEST_HEADERS':True,

#'USE_SESSION_AUTH': True,

#'DOC_EXPANSION': 'list',

# 接口文档中方法列表以首字母升序排列'APIS_SORTER': 'alpha',

# 如果支持json提交, 则接口文档中包含json输入框'JSON_EDITOR': True,

# 方法列表字母排序'OPERATIONS_SORTER': 'alpha','VALIDATOR_URL': None,

}

配置serializers.py

进入api(应用目录)，新建文件serializers.py，内容如下：

# 序列化

from django.contrib.auth.models import User,Group

from rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):

class Meta:

model=User

fields= "__all__"class GroupSerializer(serializers.HyperlinkedModelSerializer):

class Meta:

model=Group

fields= "__all__"

这里是将django自带的2个表，进行序列化。

配置views.py

进入api(应用目录)，修改views.py，完整内容如下：

from django.shortcuts import render, HttpResponse

from django.contrib.auth.models import User, Group

from rest_framework import viewsets

from api.serializers import UserSerializer, GroupSerializer

# Create your views here.

class UserViewSet(viewsets.ModelViewSet):"""retrieve:

返回用户实例

list:

返回所有用户，按最近加入的用户排序

create:

创建新用户

delete:

删除现有用户

partial_update:

更新现有用户上的一个或多个字段

update:

更新用户""" '''查看，编辑用户的界面'''queryset= User.objects.all().order_by('id')

serializer_class=UserSerializer

print(serializer_class, type(serializer_class))

class GroupViewSet(viewsets.ModelViewSet):'''retrieve:

返回组实例

list:

返回按最近加入的组排序的所有组

create:

创建新组

delete:

删除现有组

partial_update:

更新现有组上的一个或多个字段

update:

更新一个组''' '''查看，编辑组的界面'''queryset=Group.objects.all()

serializer_class= GroupSerializer

View Code

注意：这里不需要return，它会返回表数据的。

配置urls.py

修改文件t_swagger/urls.py，完整内容如下：

from django.contrib import admin

from django.urls import path,include

from rest_framework import routers # 路由配置模块

from api import views

# 路由

router=routers.DefaultRouter()

router.register(r'users',views.UserViewSet,base_name='user')

router.register(r'groups',views.GroupViewSet)

# 重要的是如下三行

from rest_framework.schemas import get_schema_view

from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer

schema_view= get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns=[

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

path('',include(router.urls)),

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

path('docs/',schema_view,name='docs'),

]

生成表

python3 manage.py makemigrations

python3 manage.py migrate

创建超级用户

python3 manage.py createsuperuser

注意：密码必须符合复杂性要求。

启动项目

直接使用Pycharm启动即可。

三、访问页面

drf自带的接口UI

http://127.0.0.1:8000/

效果如下：

Swagger UI

http://127.0.0.1:8000/docs/

效果如下：

点击users

点击get-->try it out

点击执行

结果如下：

这里是返回了一条用户表数据，"username": "xiao"，就是我新建的超级用户。

点击Authorize

输入新建的超级用户和密码

登录成功后，效果如下：