您现在的位置是:首页 >学无止境 >Swagger文档注释网站首页学无止境

Swagger文档注释

一路向东_ 2023-05-16 20:00:02
简介Swagger文档注释

本文以DRF框架为例使用

为什么要接口文档注释

    一. 方便后端调试与后续接口更新;

    二. 对于大型前后端分离项目,前后端人员是分开开发的,甚至前端的人你都不知道远在何处,这时候接口文档的重要性就太重要了。

    三. 接口注释文档常用apidoc和swagger,目前而已swagger较为流行。

本文带你从零到一将swagger用入实际开发

官网URL:https://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(      title="Snippets API",      default_version='v1',      description="Test description",      terms_of_service="https://www.google.com/policies/terms/",      contact=openapi.Contact(email="contact@snippets.local"),      license=openapi.License(name="BSD License"),   ),   public=True,   permission_classes=(permissions.AllowAny,),)urlpatterns = [   path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),   path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),   path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc')]

可以通过手写路由,完成模糊化配置:

re_path(r"^swagger(?P<format>.json|.yaml)$", schema_view.without_ui(cache_timeout=0), name="schema-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(        method='get',        operation_summary='获取电话',        operation_description="GET /phone/",        manual_parameters=[            openapi.Parameter("id", in_=openapi.TYPE_NUMBER, description="ID", type=openapi.TYPE_NUMBER)        ],        responses={status.HTTP_200_OK:PhoneNumSerializer()})

(manual_parameters中的in_和type需都存在

还有参数depracated=True 表示API已经 被弃用)

2、最简单的使用就↓

    @swagger_auto_schema(        operation_summary='POST摘要',        operation_description='POST的說明:一般用方法+请求路径',    )

还有post添加参数的方式,如:

使用request_body=openapi.Schema(....),required=[请求字段],

还有很多使用参数官网使用即可。

风语者!平时喜欢研究各种技术,目前在从事后端开发工作,热爱生活、热爱工作。