使用aiohttp和apispec构建和记录restapi
aiohttp-apispec-patch的Python项目详细描述
aiohttp API规范
在
在
在
在
aiohttp-apispec主要功能：
docs和request_schema修饰符 添加现成的swagger规范支持validation_middleware启用验证的中间件 用那些装潢师的棉花糖图案- SwaggerUI支持。在
- New from version 2.0-
match_info_schema，querystring_schema，form_schema、json_schema、headers_schema和{} 装饰器用于特定请求零件验证。 查看here了解更多信息。在
aiohttp-apispecapi完全受flask-apispec库的启发
目录
- Install
- Quickstart
- Adding validation middleware
- More decorators
- Custom error handling
- Build swagger web client
安装
pip install aiohttp-apispec
快速启动
^{pr2}$还支持基于类的视图：
classTheView(web.View):@docs(tags=["mytag"],summary="View method summary",description="View method description",)@request_schema(RequestSchema(strict=True))@response_schema(ResponseSchema(),200)defdelete(self):returnweb.json_response({"msg":"done","data":{"name":self.request["data"]["name"]}})app.router.add_view("/v1/view",TheView)
作为替代，您可以将响应信息添加到docs装饰器，这是一种更紧凑的方式。
不允许对其使用架构和响应：
@docs(tags=["mytag"],summary="Test method summary",description="Test method description",responses={200:{"schema":ResponseSchema,"description":"Success response",},# regular response404:{"description":"Not found"},# responses without schema422:{"description":"Validation error"},},)@request_schema(RequestSchema(strict=True))asyncdefindex(request):returnweb.json_response({"msg":"done","data":{}})
添加验证中间件
fromaiohttp_apispecimportvalidation_middleware...app.middlewares.append(validation_middleware)
现在您可以从request['data']访问路由中的所有已验证数据，如下所示：
@docs(tags=["mytag"],summary="Test method summary",description="Test method description",)@request_schema(RequestSchema(strict=True))@response_schema(ResponseSchema,200)asyncdefindex(request):uid=request["data"]["id"]name=request["data"]["name"]returnweb.json_response({"msg":"done","data":{"info":f"name - {name}, id - {uid}"}})
您可以将Request的'data'参数改为另一个参数为request_data_name的参数
setup_aiohttp_apispec函数：
setup_aiohttp_apispec(app=app,request_data_name="validated_data",)...@request_schema(RequestSchema(strict=True))asyncdefindex(request):uid=request["validated_data"]["id"]...
也可以使用put_into为特定视图执行此操作
参数（从版本2.0开始）：
@request_schema(RequestSchema(strict=True),put_into="validated_data")asyncdefindex(request):uid=request["validated_data"]["id"]...
更多的装饰师
从版本2.0开始，您可以使用缩写来记录和验证 使用这些修饰符的特定请求部分，如cookies、header等：
| Decorator name | Default put_into param |
|---|---|
| match_info_schema | match_info |
| querystring_schema | querystring |
| form_schema | form |
| json_schema | json |
| headers_schema | headers |
| cookies_schema | cookies |
例如：
@docs(tags=["users"],summary="Create new user",description="Add new user to our toy database",responses={200:{"description":"Ok. User created","schema":OkResponse},401:{"description":"Unauthorized"},422:{"description":"Validation error"},500:{"description":"Server error"},},)@headers_schema(AuthHeaders)# <- schema for headers validation@json_schema(UserMeta)# <- schema for json body validation@querystring_schema(UserParams)# <- schema for querystring params validationasyncdefcreate_user(request:web.Request):headers=request["headers"]# <- validated headers!json_data=request["json"]# <- validated json!query_params=request["querystring"]# <- validated querystring!...
自定义错误处理
如果您想自己捕捉验证错误
无法使用error_callback参数并创建自定义错误处理程序。请注意
它可以是一个协同程序或可调用的，它应该
具有与以下示例完全相同的接口：
frommarshmallowimportValidationError,SchemafromaiohttpimportwebfromtypingimportOptional,Mapping,NoReturndefmy_error_handler(error:ValidationError,req:web.Request,schema:Schema,error_status_code:Optional[int]=None,error_headers:Optional[Mapping[str,str]]=None,)->NoReturn:raiseweb.HTTPBadRequest(body=json.dumps(error.messages),headers=error_headers,content_type="application/json",)setup_aiohttp_apispec(app,error_callback=my_error_handler)
也可以创建自己的异常并创建 中间件中的常规请求如下：
classMyException(Exception):def__init__(self,message):self.message=message# It can be coroutine as well:asyncdefmy_error_handler(error,req,schema,error_status_code,error_headers):awaitreq.app["db"].do_smth()# So you can use some async stuffraiseMyException({"errors":error.messages,"text":"Oops"})# This middleware will handle your own exceptions:@web.middlewareasyncdefintercept_error(request,handler):try:returnawaithandler(request)exceptMyExceptionase:returnweb.json_response(e.message,status=400)setup_aiohttp_apispec(app,error_callback=my_error_handler)# Do not forget to add your own middleware before validation_middlewareapp.middlewares.extend([intercept_error,validation_middleware])
构建swagger web客户端
3.X SwaggerUI版本
只需将swagger_path参数添加到setup_aiohttp_apispec函数中。在
例如：
setup_aiohttp_apispec(app,swagger_path="/docs")
那就去/docs看一看真棒的招摇过市
2.X SwaggerUI版本
如果您喜欢旧版本，可以使用
aiohttp_swagger库。
aiohttp-apispec向aiohttp web应用程序添加swagger_dict参数
初始化后（使用setup_aiohttp_apispec函数）。
因此，您可以很容易地使用它，例如：
fromaiohttp_apispecimportsetup_aiohttp_apispecfromaiohttp_swaggerimportsetup_swaggerdefcreate_app(app):setup_aiohttp_apispec(app)asyncdefswagger(app):setup_swagger(app=app,swagger_url="/api/doc",swagger_info=app["swagger_dict"])app.on_startup.append(swagger)# now we can access swagger client on '/api/doc' url...returnapp
如果这个项目对你有帮助的话，请给这个资料库加上星号！在
- 项目
标签：
欢迎加入QQ群-->： 979659372
