Backend - Django Swagger

这篇具有很好参考价值的文章主要介绍了Backend - Django Swagger。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

目录

一、安装依赖

二、配置环境

三、路由(urls)

四、swagger UI 界面

(一)UI 界面

(二)单引号问题:Expecting property name enclosed in double quotes

1. 原因

2. 解决

五、自定义swagger文档

(一)装饰器 @swagger_auto_schema

1. 属性认知

2. manual_parameters属性

(1)name:参数名

(2)in_:参数位于 request 的 某个位置

(3)type:参数类型

 (二)应用

1. 导入依赖

2. 自定义openapi.Parameter参数

3. 自定义openapi.Schema参数

4. 自定义openapi.Response参数

5. views内容 

六、API被弃用


一、安装依赖

pip install drf-yasg==1.21.5

二、配置环境

# settings.py文件中
INSTALLED_APPS = [
    ...
    'drf_yasg',  # 注意是drf_yasg,而不是drf-yasg
    ...
]

三、路由(urls)

from django.urls import path, re_path  # url规则
from rest_framework import permissions   # API的访问权限
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
from myBook import views as book_view

# 基础设置
schema_view = get_schema_view(
	openapi.Info(
		title="Books API",
		default_version='v1',
		description="Books' RESTful API documentation.",
		terms_of_service="https://www.google.com/policies/terms/",
		contact=openapi.Contact(email="XXX"),
		license=openapi.License(name="BSD License"),
	),
	public=True,
	permission_classes=[permissions.AllowAny],
)

# 补充swagger路由
urlpatterns += [
	re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
	re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
	re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

四、swagger UI 界面

(一)UI 界面

        浏览器输入swagger UI 的链接: http://127.0.0.1:8000/swagger/

        注意:

        1. 链接XXX/swagger尾巴,还有后缀“/”。

        2. 只要符合restful API序列化类写法的对应路由,就会呈现在swagger UI界面上。

Backend - Django Swagger,django,python,后端,drf,swagger

针对Django 序列化,可参考另一篇文章:Backend - DRF 序列化(django-rest-framework)-CSDN博客    

(二)单引号问题:Expecting property name enclosed in double quotes

1. 原因

        swagger UI界面中,字典里的引号都得用双引号,而不是单引号。

2. 解决

        python代码里,将单引号替换成双引号。

import json 
my_str.replace("\'", "\"")
my_dict = json.loads(my_str)

五、自定义swagger文档

(一)装饰器 @swagger_auto_schema

1. 属性认知

        以get方法的@swagger_auto_schema装饰器为例,一般情况下有operation_summary、operation_description、manual_parameters、responses等属性。

# 所需依赖
from rest_framework import status  # Django REST Framework
from drf_yasg import openapi  # Swagger
from drf_yasg.utils import swagger_auto_schema  # Swagger
@swagger_auto_schema(
		operation_summary='GET 概括', 
		operation_description='GET 描述',
		manual_parameters=[
			openapi.Parameter(
				name='bookname',  # name是用来确定唯一值的(不能重复)
				description='这是描述',
				in_=openapi.IN_QUERY,
				type=openapi.TYPE_STRING,
				required=True,
			)
		],
		responses={
			status.HTTP_200_OK: openapi.Response(
				description='Success',
				schema=openapi.Schema(
					type=openapi.TYPE_OBJECT,
					properties={
						'result':  openapi.Schema(type=openapi.TYPE_BOOLEAN, description='successful!'),
						'resData': openapi.Schema(
												type=openapi.TYPE_ARRAY, 
												items=openapi.Schema(
													type=openapi.TYPE_OBJECT, 
													description='该列表的items是个dict,分别有key值为key1和key2', 
													properties={'key1': openapi.Schema(type=openapi.TYPE_INTEGER, description='第一个值'),
																'key2': openapi.Schema(type=openapi.TYPE_STRING, description='第二个值'),}
												),
									),
					},
				),
			),
			status.HTTP_401_UNAUTHORIZED: openapi.Response(
				description='Unauthorized',
				schema=openapi.Schema(
									type=openapi.TYPE_OBJECT,
									properties={'result': openapi.Schema(type=openapi.TYPE_BOOLEAN, description='HTTP 401 UNAUTHORIZED.')}
						),
			),
		},
	)

2. manual_parameters属性

主要参数有name、in_、type。

(1)name:参数名
(2)in_:参数位于 request 的 某个位置

        其中,openapi.IN_BODY ,参数在 request 的 body,例如 POST 请求。

        openapi.IN_QUERY ,参数在 request 的 quey,例如 user/?authorname='萝卜干'  。

        openapi.IN_FORM ,参数在 request 的 form 表单。

        openapi.IN_PATH ,参数在 request 的 path,例如 /user/<id>/。

(3)type:参数类型

        如:openapi.TYPE_NUMBER,类型为 number。

        openapi.TYPE_STRING,类型为 string。

        openapi.TYPE_BOOLEAN,类型为 boolean。

        openapi.TYPE_FILE,类型为 file。

 (二)应用

        以下内容都写在同一个views.py中。

1. 导入依赖

from myApp import myserializer
from myApp.myserializer import AuthorApi
from drf_yasg import openapi  # Swagger
from drf_yasg.utils import swagger_auto_schema  # Swagger
from rest_framework.generics import GenericAPIView  # Django REST Framework
from rest_framework import status  # Django REST Framework

2. 自定义openapi.Parameter参数

class manualParam:
        my_str = openapi.Parameter(
            name='bookname',  # name是用来确定唯一值的(不能重复)
            description='这是描述',
            in_=openapi.IN_QUERY,
            type=openapi.TYPE_STRING,
            required=True,
        )
        my_num = openapi.Parameter(
            name='authorname',
            description='这是描述',
            in_=openapi.IN_QUERY,
            type=openapi.TYPE_NUMBER,
            required=False,
        )

3. 自定义openapi.Schema参数

    class manualRes:
        res200 = openapi.Schema(type=openapi.TYPE_BOOLEAN, description='successful!')
        res401 = openapi.Schema(type=openapi.TYPE_BOOLEAN, description='HTTP 401 UNAUTHORIZED.')
        books_properties ={'key1': openapi.Schema(type=openapi.TYPE_INTEGER, description='第一个值'),'key2': openapi.Schema(type=openapi.TYPE_STRING, description='第二个值'),}
        resData = openapi.Schema(
                    type=openapi.TYPE_ARRAY, 
                    items=openapi.Schema(type=openapi.TYPE_OBJECT, description='该列表的items是个dict,分别有key值为key1和key2', properties=books_properties ),
                )

4. 自定义openapi.Response参数

# 和“(3)自定义openapi.Schema参数”在同一个类中
class manualRes:
    # Success 成功 200
    response_200 = openapi.Response(
                description='Success',
                schema=openapi.Schema(
                    type=openapi.TYPE_OBJECT,
                    properties={
                        'result': res200,
                        'resData': resData,
                    },
                ),
            )
 
    # Unauthorized 无权限 401 
    response_401 = openapi.Response(
        description='Unauthorized',
        schema=openapi.Schema(type=openapi.TYPE_OBJECT,properties={'result': res401}),
    )

5. views内容 

    class Book(GenericAPIView):
        @swagger_auto_schema(
            operation_summary='该 get 的概括', 
            operation_description='该 get 的描述', 
            manual_parameters=[
                manualParam.my_str,
                manualParam.my_num
            ],
            responses={
                status.HTTP_200_OK: manualRes.response_200,
                status.HTTP_401_UNAUTHORIZED: manualRes.response_401,
            },
        )
        def get(self, request, *args, **kwargs):
            try:
                reqdata = request.data
                res = AuthorApi(data=reqdata) # 使用序列化器
            except Exception as e:
                pass
            return JsonResponse()
        @swagger_auto_schema(
            operation_summary='该 post 的概括', operation_description='该 post 的描述', request_body=myserializer.SerializerBookCreate,
        )
        def post(self, request, *args, **kwargs):
            try:
                pass
            except Exception as e:
                pass
            return JsonResponse()
        @swagger_auto_schema(
            operation_summary='该 delete 的概括', operation_description='该 delete 的描述', request_body=myserializer.SerializerBookDelete,
        )
        def delete(self, request, *args, **kwargs):
            try:
                pass
            except Exception as e:
                pass
            return JsonResponse()
        @swagger_auto_schema(
            operation_summary='该 patch 的概括', operation_description='该 patch 的描述', request_body=myserializer.SerializerBookPatch,
        )
        def patch(self, request, *args, **kwargs):
            try:
                pass
            except Exception as e:
                pass
            return JsonResponse()

六、API被弃用

若想提示某API已被弃用,则设置 depracated=True。

例如:文章来源地址https://www.toymoban.com/news/detail-855808.html

@swagger_auto_schema(
    operation_summary='该 post 的概括',
    operation_description='该 post 的描述',
    depracated=True 
)

到了这里,关于Backend - Django Swagger的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • Django认证流程源码及自定义 Backend

    因为Django自带的authenticate只能帮你验证用户名和密码,当你需要验证使用如手机号登录、邮箱登录、验证码登录等时,需要自己重写authenticate方法,自定义认证方式

    2024年02月07日
    浏览(29)
  • 【Django 05】Django-DRF(ModelViewSet)、路由组件、自定义函数

    ModelViewSet 是 Django REST framework 提供的一个视图集类,它封装了常见的模型操作方法。 模型类提供了默认的增删改查功能。 它继承自 GenericViewSet 、 ListModelMixin 、 RetrieveModelMixin 、 CreateModelMixin 、 UpdateModelMixin 、 DestoryModelMixin 。 知识点 请求 url 特点 GenericViewSet 提供一组通用的

    2024年02月08日
    浏览(42)
  • Django系列之DRF简单使用

    models.py serializers.py app01/views.py project/urls.py app01/urls.py 使用 SimpleRouter() 可以帮我们实现五个基础的 action 方法: {“get”: “list”, “post”: “create”, “get/id”: “retrieve”, “put”: “update”, “delete”: “`destroy”} 如果需要增加一些其他的路由视图,就需要用 action 声明了。

    2024年02月15日
    浏览(35)
  • Django DRF - 【Token】认证基本使用

    Django Rest Framework Token 是Django Rest Framework中的一个扩展,用于实现用户认证和授权。它为每个用户生成一个唯一的Token,并将其存储在数据库中。在用户进行API请求时,用户需要在请求的HTTP Header中包含Token,这样服务器就可以验证用户的身份。 迁移完成会生成 authtoken_token 这张

    2024年02月12日
    浏览(36)
  • Django系列之DRF搜索和过滤

    1. model之间关系 2. DRF搜索 在DRF中使用搜索功能,只需要在 viewsets 视图类中定义 filter_backends 和 search_fields 即可使用。 filter_backends :后端使用的搜索和过滤类。 search_fields :要执行搜索条件的字段,搜索为模糊查询(要在哪些字段上执行模糊查询,支持多表连表查询)。 对应

    2024年02月07日
    浏览(40)
  • django框架向DRF框架演变过程详解

    主要知识点: Django框架 视图函数 1、在 Django 项目中创建一个应用(如果还没有创建): 2、在项目的 models.py 文件中定义项目模型 3、运行数据库迁移命令,以创建项目表: 4、在应用的 views.py 文件中编写视图函数来处理查询项目列表的请求: 5、在项目的 urls.py 文件中配置

    2024年02月16日
    浏览(40)
  • Django_rest_framework-drf 笔记

    Django-drf-序列化器高级用法之SerializerMethodField - 知乎 (zhihu.com) 一句话: search_fields  里的字段,是做模糊查询的字段; filter_fields  里的字段,是做精确查询的字段。 科普search_fields与filter_fields的区别_空气中的臭氧的博客-CSDN博客 一句话: related_name = \\\'test\\\' publish_obj.test.all() 

    2024年02月16日
    浏览(38)
  • Django实现DRF数据API接口格式封装

    当进行前后端分离开发时,前端Vue通常需要与后端接口交互并获取数据。初始情况下数据可能是这样的:

    2024年02月11日
    浏览(45)
  • Django--DRf---序列化器:序列化器嵌套

    模型表: 1、方式一:通过source来获取指定字段数据 【一对多和一对一的】 1.1、一对多 外键方 1.2、多对多 外键方 【不适应】 2、方式二:通过外键=序列化类() 【适用所有关系】 2.1、多对多:外键在这里 序列化器: 视图类: 2.2、一对多,外键方 【学生表,嵌套班级】 3、

    2024年02月01日
    浏览(41)
  • 七、Django DRF框架GenericAPIView--搜索&排序&分页&返回值

    上一章: 六、DRF框架APIView--requestresponse解析器渲染器_做测试的喵酱的博客-CSDN博客 下一章: APIView 继承 View GenericAPIView 继承 APIView。 GenericAPIView 功能:     a.具备View的所有特性     b.具备了APIView中的认证、授权、限流功能     c.还支持对于获取列表数据接口的功能:搜索

    2024年02月08日
    浏览(74)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包