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
输入新建的超级用户和密码
登录成功后，效果如下：