与AIOHTTP和APISPEC一起建立和文档
aiohttp-apispec的Python项目详细描述
AIOHTP API规范
aiohttp-apispec主要功能：
docs和request_schema装饰器 要添加现成的夸张规格支持；validation_middleware启用验证的中间件 使用来自那些装饰者的棉花糖模式；- swaggerui支持。
aiohttp-apispecapi完全受flask-apispec库的启发
内容
安装
pip install aiohttp-apispec
快速启动
fromaiohttp_apispecimport(docs,request_schema,setup_aiohttp_apispec,)fromaiohttpimportwebfrommarshmallowimportSchema,fieldsclassRequestSchema(Schema):id=fields.Int()name=fields.Str(description="name")@docs(tags=["mytag"],summary="Test method summary",description="Test method description",)@request_schema(RequestSchema(strict=True))asyncdefindex(request):returnweb.json_response({"msg":"done","data":{}})app=web.Application()app.router.add_post("/v1/test",index)# init docs with all parameters, usual for ApiSpecsetup_aiohttp_apispec(app=app,title="My Documentation",version="v1",url="/api/docs/swagger.json",swagger_path="/api/docs",)# Now we can find spec on 'http://localhost:8080/api/docs/swagger.json'# and docs on 'http://localhost:8080/api/docs'web.run_app(app)
也支持基于类的视图：
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)
作为替代方案，您可以将响应信息添加到docsdecorator，这是一种更紧凑的方式。
它允许您不使用模式来编写响应文档：
@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"]...
自定义错误处理
如果您想自己捕捉验证错误，您可以
可以使用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)
也可以创建自己的异常并创建 中间件中的常规请求，如so:
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])
构建夸张的Web客户端
3.x SwaggerUI版本
只需将swagger_path参数添加到setup_aiohttp_apispec函数。
例如：
setup_aiohttp_apispec(app,swagger_path="/docs")
然后转到/docs并查看awesome swaggerui
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
