Django + drf-yasg实现在线接口文档-代码实测
目录
使用示例
settings.py
urls.py
新建config.swagger.py
apps.urls.py
apps.views.py
装饰器使用介绍
swagger_auto_schema使用
Parameter使用
Schema使用
Response使用
安装
pip install drf_yasg使用示例
settings.py
INSTALLED_APPS:
INSTALLED_APPS = [
......
'rest_framework',
'drf_yasg',
]SWAGGER_SETTINGS:
SWAGGER_SETTINGS = {
'DEFAULT_AUTO_SCHEMA_CLASS': 'config.swagger.CustomSwaggerAutoSchema',
'SECURITY_DEFINITIONS': {
'Token': {
'type': 'apiKey', #
'name': 'Authorization',
'in': 'header'
},
'Token2': {
'type': 'apiKey',
'name': 'Authorization',
'in': 'header'
}
}
}urls.py
from django.contrib import admin
from django.urls import path, include, re_path
# drf_yasg 从这里开始
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
openapi.Info(
title="Tweet API",
default_version='v1',
description="Welcome to the world of Tweet",
terms_of_service="https://www.tweet.org",
contact=openapi.Contact(email="[email protected]"),
license=openapi.License(name="Awesome IP"),
),
public=True,
permission_classes=(permissions.AllowAny,), # 权限类
)
# 这里结束
urlpatterns = [
path('admin/', admin.site.urls),
path('user/', include("users.urls")),
re_path(r'^doc(?P\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'), # <-- 这里
path('doc/', 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'), # <-- 这里
]
新建config.swagger.py
分组功能！
from drf_yasg.inspectors import SwaggerAutoSchema
class CustomSwaggerAutoSchema(SwaggerAutoSchema):
def get_tags(self, operation_keys=None):
tags = super().get_tags(operation_keys)
if "v1" in tags and operation_keys:
# `operation_keys` 内容像这样 ['v1', 'prize_join_log', 'create']
tags[0] = operation_keys[1]
return tags
apps.urls.py
# -*- coding: utf-8 -*-
from django.urls import path
from . import views
urlpatterns = [
path('user/list', views.UserView.as_view({'post': 'list'})),
]apps.views.py
views中必须继承ViewSet或者APIView！
# -*- coding: utf-8 -*-
from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema
from rest_framework.viewsets import ViewSet
tags = ['WlUser']
class UserView(ViewSet):
@swagger_auto_schema(
operation_description="apiview post description override",
request_body=openapi.Schema(
type=openapi.TYPE_OBJECT,
required=['page', 'pageSize'],
properties={
'page': openapi.Schema(type=openapi.TYPE_NUMBER),
'pageSize': openapi.Schema(type=openapi.TYPE_NUMBER),
},
),
security=[], tags=tags, operation_summary='列表')
def list(self, request):
pass
运行项目，访问：http://localhost:8000/doc/ ， http://localhost:8000/redoc/
装饰器使用介绍
查看drf_yasg.openapi模块中的 20-56行，介绍了 type,format,in_三个参数的类型，他们值都进行了常量化
type有:
"object" ,"string" ,"number" ,"integer" ,"boolean" ,"array" ,"file"
format有：
date,date-time,password,binary,bytes,float,double,int32,int64,email,
ipv4,ipv6,uri,uuid,slug,decimal等类型
in_参数(代表参数在什么位置)有：
body,path,query,formData,header
Parameter:用来构造请求参数
Schema：对参数进行补充说明，属性说明等
Response：用来构造单个响应数据的 比如200状态码对应的响应
Responses：用来构造多个响应数据的 {200:正常响应,401:验证未通过响应}swagger_auto_schema使用
def swagger_auto_schema(
method=None, # 单个请求方法 GET 类方法下不需要
methods=None, # 请求方法的列表 ['GET','POST'] 类方法下不需要
auto_schema=unset,
request_body=None, # 请求体 Schema对象
query_serializer=None, # serializer类
manual_parameters=None, # 参数列表 [Parameter对象列表] 可以通过in_=IN_PATH，来修饰path中的参数
operation_id=None, # API的唯一编号 可以不填
operation_description=None, # 对该API的描述信息
operation_summary=None, # 接口名称
security=None, # 安全
deprecated=None, # 是否弃用
responses=None, # 响应体 {200：Response对象，401：serializer类}
dict[int or str, (drf_yasg.openapi.Schema or drf_yasg.openapi.SchemaRef or
drf_yasg.openapi.Response or str or rest_framework.serializers.Serializer)]
field_inspectors=None,
filter_inspectors=None,
paginator_inspectors=None,
tags=None, # 模块名称
**extra_overrides):Parameter使用
class Parameter(SwaggerDict):
def __init__(self, name, in_, description=None, required=None, schema=None,
type=None, format=None, enum=None, pattern=None, items=None, default=None, **extra):
name:参数名称
in_:参数位置 参见 装饰器使用前介绍 部分
description：参数描述
required：是否必须
schema：当in_是body时，schema对象
type:类型 参见 装饰器使用前介绍 部分
format:格式 参见 装饰器使用前介绍 部分
enum：(列表) 列举参数的请求值(请求值只在这几个值中)
pattern：当 format为 string是才填此项
items：
default：Schema使用
class Schema(SwaggerDict):
def __init__(self, title=None, description=None, type=None, format=None, enum=None, pattern=None, properties=None,additional_properties=None, required=None, items=None, default=None, read_only=None, **extra):
title：标题(可以不填)
description：描述
type:类型 参见 装饰器使用前介绍 部分
format:格式 参见 装饰器使用前介绍 部分
enum：(列表) 列举参数的请求值(请求值只在这几个值中)
pattern：当 format为 string是才填此项
properties: 当 type为object时，为dict对象
{'str1':Schema对象,'str2':SchemaRef对象}
required：[必须的属性列表]
items：当type是array时，填此项
default：Response使用
class Response(SwaggerDict):
def __init__(self, description, schema=None, examples=None, **extra):
description：字符串
schema：Schema对象
examples：dict对象