发布时间:2020-08-03 10:16:29编辑:admin阅读(2836)
当接口开发完成,紧接着需要编写接口文档。传统的接口文档使用Word编写,or一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次接口有变更,需要手动修改接口文档。为了改善这种情况,推荐使用Swagger来管理接口文档,实现接口文档的自动更新。
Swagger:是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。当接口有变动时,对应的接口文档也会自动更新。
如:接口测试站点(http://httpbin.org/#/),也是利用Swagger来生成接口文档
1)Swagger可生成一个具有互动性的API控制台,开发者可快速学习和尝试API
2)Swagger可生成客户端SDK代码,用于不同平台上(Java、Python...)的实现
3)Swagger文件可在许多不同的平台上从代码注释中自动生成
4)Swagger有一个强大的社区,里面有许多强悍的贡献者
1.安装django-rest-swagger
2.进入到setting.py文件,添加django-rest-swagger应用
3.进入到views.py,将之前定义的UserViewSet和GroupViewset补充注释
4.在urls.py中添加get_schema_view辅助函数
5.启动Django服务,检测Swagger接口文档配置效果
python 3.7.3
Django 2.2.4
djangorestframework==3.9.2
django-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。
使用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,
}
进入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个表,进行序列化。
进入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
注意:这里不需要return,它会返回表数据的。
修改文件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启动即可。
http://127.0.0.1:8000/
效果如下:
http://127.0.0.1:8000/docs/
效果如下:
点击users
点击get-->try it out
点击执行
结果如下:
这里是返回了一条用户表数据,"username": "xiao",就是我新建的超级用户。
点击Authorize
输入新建的超级用户和密码
登录成功后,效果如下:
本文参考链接:
https://www.jianshu.com/p/c53de96f3ff1
https://blog.csdn.net/sinat_41622641/article/details/81636682
https://blog.csdn.net/the_brave/article/details/106138396
48304
47096
37976
35269
29766
26443
25390
20386
20069
18518
31°
38°
71°
141°
119°
313°
177°
162°
228°
375°