Django关于drf_yasgApi文档使用示例

配置

settings.pyINSTALLED_APPS=[

    ...

'drf_yasg',

    ...

]

```

urls.pyfromrest_frameworkimportpermissions

fromdrf_yasg.viewsimportget_schema_view

fromdrf_yasgimportopenapi

schema_view=get_schema_view(

openapi.Info(

title="平台API文档",

default_version='v1',

description="Welcometo***",

#terms_of_service="https://www.tweet.org",

#contact=openapi.Contact(email="demo@tweet.org"),

#license=openapi.License(name="AwesomeIP"),

),

public=True,

#我也添加了此处但是还是有权限问题

permission_classes=(permissions.AllowAny,),

)

#对测试人员更友好

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'),

验证权限问题测试的时候报403方法1：#注释掉此处就可访问到文档

REST_FRAMEWORK={

"DEFAULT_AUTHENTICATION_CLASSES":['user_profile.utils.auth.CustomAuthentication',],

}

方法2：对doc创建一个验证类classDRFdocAuthentication(BaseAuthentication):

defauthenticate(self,request):

token_obj=models.UserToken.objects.first()

returntoken_obj.user,token_obj

defauthenticate_header(self,request):

pass

然后在该处添加此行，即可正常访问get_schema_view(

public=True,

#添加此行

authentication_classes=(DRFdocAuthentication,)

)

api文档编写使用fromdrf_yasg.utilsimportswagger_auto_schema

classPolygonView(APIView):

    #使用该装饰器

@swagger_auto_schema()

defget(self,request,generate_id):

    pass

装饰器使用前介绍查看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使用

    defswagger_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[intorstr,(drf_yasg.openapi.Schemaordrf_yasg.openapi.SchemaRefor

    drf_yasg.openapi.Responseorstrorrest_framework.serializers.Serializer)]

    field_inspectors=None,

    filter_inspectors=None,

    paginator_inspectors=None,

    tags=None,#模块名称

    **extra_overrides):

Parameter使用

classParameter(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使用

classSchema(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使用

classResponse(SwaggerDict):

def__init__(self,description,schema=None,examples=None,**extra):

description：字符串

schema：Schema对象

examples：dict对象

PUT请求示例

polygon_view_put_desc='根据generate_id修改一个图斑'

polygon_view_put_parm=Schema(type=TYPE_OBJECT,properties={

'reason':Schema(description='变化原因example:造林更新',type=TYPE_STRING),

'village':Schema(description='所属乡镇example:石马镇',type=TYPE_STRING),

'remarks':Schema(description='备注example:...',type=TYPE_STRING),

'real_area':Schema(description='实测面积example:2020',type=TYPE_NUMBER),

'disguise_change':Schema(description='是否是伪变化example:0表示不是,1表示是',type=TYPE_INTEGER,enum=[0,1]),

'images':Schema(description='上传图片id列表example:[1,2,3]',type=TYPE_ARRAY,items=Schema(type=TYPE_INTEGER)),#列表对象

})

polygon_view_put_resp={200:Response(description='修改成功',examples={'json':{'msg':'修改成功！',"data":[]}})}

@swagger_auto_schema(operation_description=PSW.polygon_view_put_desc,request_body=PSW.polygon_view_put_parm,responses=PSW.polygon_view_put_resp)

defput(self,request,generate_id):

    pass

请求参数效果图：响应效果：

GET请求示例

polygon_view_get_desc='根据generate_id获取返回一个图斑'

polygon_view_get_parm=[

Parameter(name='generate_id',in_=IN_PATH,description='图斑idexample:20201212125560555',type=TYPE_STRING,required=True),

Parameter(name='year',in_=IN_QUERY,description='年份example:2020',type=TYPE_INTEGER,required=False),

Parameter(name='quarter',in_=IN_QUERY,description='季度例如：1代表一季度',required=False,type=TYPE_INTEGER,enum=[1,2,3,4,5]),

]

polygon_view_get_resp={200:DiffPolygonSerializer}

@swagger_auto_schema(operation_description=PSW.polygon_view_get_desc,manual_parameters=PSW.polygon_view_get_parm,responses=PSW.polygon_view_get_resp)

defget(self,request,generate_id):

    pass

效果图：响应结果