网站建设算什么费用,设计网站账号,东莞人才市场在哪里,成都住房和城乡建设部网站本文以DRF框架为例使用
为什么要接口文档注释 一. 方便后端调试与后续接口更新#xff1b; 二. 对于大型前后端分离项目#xff0c;前后端人员是分开开发的#xff0c;甚至前端的人你都不知道远在何处#xff0c;这时候接口文档的重要性就太重要了。 三. 接口注释文档常用…本文以DRF框架为例使用
为什么要接口文档注释 一. 方便后端调试与后续接口更新 二. 对于大型前后端分离项目前后端人员是分开开发的甚至前端的人你都不知道远在何处这时候接口文档的重要性就太重要了。 三. 接口注释文档常用apidoc和swagger目前而已swagger较为流行。 本文带你从零到一将swagger用入实际开发
官网URLhttps://pypi.org/project/drf-yasg/#quickstart
本文会把必要操作都实现不点也可以毕竟文档全英
安装
pip install -U drf-yasg 在外层目录创建目录命名swagger即可先创建一个urls.py文件。
全文搜索看你项目的INSTALLED_APPS在哪里然后在配置文件内加入
INSTALLED_APPS [...django.contrib.staticfiles, # 为swagger的ui css/js文件提供服务时需要drf_yasg,...
] 然后写urls先在外层的urls写入路由
from swagger import urls as swagger_urlsurlpatterns [ ... url(r^, include(swagger_urls)), ...]
swagger/urls.py
下列的swagger和redoc其实就是不同模板的视图展示甚至还有swagger.json和swagger.yaml的API规范的JSON视图与yaml视图
from django.urls import re_pathfrom rest_framework import permissionsfrom drf_yasg.views import get_schema_viewfrom drf_yasg import openapischema_view get_schema_view( openapi.Info( titleSnippets API, default_versionv1, descriptionTest description, terms_of_servicehttps://www.google.com/policies/terms/, contactopenapi.Contact(emailcontactsnippets.local), licenseopenapi.License(nameBSD License), ), publicTrue, permission_classes(permissions.AllowAny,),)urlpatterns [ path(swaggerformat/, schema_view.without_ui(cache_timeout0), nameschema-json), path(swagger/, schema_view.with_ui(swagger, cache_timeout0), nameschema-swagger-ui), path(redoc/, schema_view.with_ui(redoc, cache_timeout0), nameschema-redoc)]
可以通过手写路由完成模糊化配置
re_path(r^swagger(?Pformat\.json|\.yaml)$, schema_view.without_ui(cache_timeout0), nameschema-json), 此时运行项目在路径后加/swagger
可以看到类似这种界面↓ 加/redoc可以看到类似这种界面Download可导出json或yaml文件 到这里swagger集成的初步工作就完成了。
接下来就是去方法中加注解
swagger_auto_schema
去标记
例如
1、Get方法获取电话号method为方法operation_summary为外注解operation_description用来表示方法请求路径manual_parameters用于声明请求参数responses展示返回信息默认会使用当前class指定的serializer swagger_auto_schema( methodget, operation_summary获取电话, operation_descriptionGET /phone/, manual_parameters[ openapi.Parameter(id, in_openapi.TYPE_NUMBER, descriptionID, typeopenapi.TYPE_NUMBER) ], responses{status.HTTP_200_OK:PhoneNumSerializer()})
manual_parameters中的in_和type需都存在
还有参数depracatedTrue 表示API已经 被弃用
2、最简单的使用就↓ swagger_auto_schema( operation_summaryPOST摘要, operation_descriptionPOST的說明一般用方法请求路径, )
还有post添加参数的方式如
使用request_bodyopenapi.Schema(....)required[请求字段], 还有很多使用参数官网使用即可。
