生成OpenAPI文档并用Python注释验证请求和响应。
flask-pydantic-spec的Python项目详细描述
烧瓶瓶规格
一个库,可以方便地将OpenAPI文档添加到Flask应用程序中,并使用Pydantic验证请求。在
{但是我们开始改变这个图书馆 其他人可能对我们的方法感兴趣。在
特点
- 样板代码更少,只有注释,不需要YAML:sparkles:
- 使用Redoc UI或Swagger UI生成API文档:yum:
- 使用pydantic:wink验证查询、JSON数据、响应数据:
- 支持JSON以外的请求/响应类型。在
快速入门
用pip安装:pip install flask-pydantic-spec
示例
检查examples文件夹。在
逐步
- 使用
pydantic.BaseModel
定义在(query,json,headers,cookies,resp)中使用的数据结构 - 使用您正在使用的web框架名称创建
flask_pydantic_spec.Validator
实例,如api = Validator('flask')
api.validate
用query
body
headers
cookies
resp
tags
- 使用
context(query, body, headers, cookies)
访问这些数据(当然,您可以从框架提供的原始位置访问这些数据)- 烧瓶:
request.context
- 猎鹰:
req.context
- 开始日期:
request.context
- 烧瓶:
- 注册到web应用程序
api.register(app)
- 请检查URL位置
/apidoc/redoc
或/apidoc/swagger
处的文档
如果请求没有通过验证,它将返回一个422和JSON错误消息(ctx,loc,msg,type)。在
如何
How to add summary and description to endpoints?
只需将docs添加到endpoint函数。第一行是摘要,其余的是对这个端点的描述。在
How to add description to parameters?
检查pydantic文档中关于^{
Any config I can change?
当然。检查config文档。在
您可以在初始化验证程序时更新配置,如下所示:
Validator('flask',title='Demo API',version='v1.0',path='doc')
What is
Response
and how to use it?
要为端点构建响应,您需要声明格式为HTTP_{code}
的状态代码和相应的数据(可选)。在
What should I return when I'm using the library?
不需要改变任何东西。只需返回框架所需的内容。在
How to logging when the validation failed?
验证错误以信息级别记录。详细信息将传递到extra
。有关详细信息,请查看falcon example。在
How can I change the response when there is a validation error? Can I record some metrics?
这个库提供了before
和after
钩子来完成这些操作。检查doc或{a12}。您可以更改Flask Pydanic Spec或特定端点验证的处理程序。在
演示
尝试使用http post :8000/api/user name=alice age=18
。(如果您正在使用httpie
)
烧瓶
fromflaskimportFlask,request,jsonifyfrompydanticimportBaseModel,Field,constrfromflask_pydantic_specimportValidator,ResponseclassProfile(BaseModel):name:constr(min_length=2,max_length=40)# Constrained Strage:int=Field(...,gt=0,lt=150,description='user age(Human)')classConfig:schema_extra={# provide an example'example':{'name':'very_important_user','age':42,}}classMessage(BaseModel):text:strapp=Flask(__name__)api=Validator('flask')@app.route('/api/user',methods=['POST'])@api.validate(body=Request(Profile),resp=Response(HTTP_200=Message,HTTP_403=None),tags=['api'])defuser_profile():""" verify user profile (summary of this endpoint) user's name, user's age, ... (long description) """print(request.context.json)# or `request.json`returnjsonify(text='it works')if__name__=="__main__":api.register(app)# if you don't register in api init stepapp.run(port=8000)
常见问题解答
ValidationError: missing field for headers
Flask中的HTTP头的密钥是大写的。
您可以使用^{
ValidationError: value is not a valid list for query
由于没有多值HTTP查询的标准,因此很难为不同的web框架找到处理这一问题的方法。所以我建议在找到合适的方法来修复它之前不要在查询中使用列表类型。在
- 项目
标签: