使用python创建api规范和文档
pactum的Python项目详细描述
pactum
pythonistas的http-api规范sketchbook
pip install pactum
使用Pactum
您可以使用纯python 指定http api。
pactum易于使用、扩展和贡献:
易于使用
使用pactum
开始编写api规范的唯一要求
是pactum
包本身和一些python知识。
importpactumclassMyAPI(pactum.API):name='My API'versions=[...]
易于扩展
使用visitor pattern可以创建 任何格式或服务的导出器和扩展。
看看pactum/exporters/openapi.py。
架构
定义api时,请始终记住this diagram。
教程
创建一个名为specs.py的文件并开始定义您的api。
您可以为api定义一个Resource
对象。
frompactumimportAction,API,Resource,Response,Versionfrompactumimportfields,verbsclassOrder(Resource):fields=[fields.IntegerField(name='code',required=True),fields.TimestampField(name='created_at'),fields.StringField(name='item')]resource=Order()error_resource=Resource(name='ErrorResource'fields=[fields.StringField(name='error',required=False)])
您可以直接调用规范的任何元素,如
error_resource
或按类定义(如MyResource
)调用它。
列表资源是同一资源列表的定义。
list_order_resource=ListResource(resource=resource)
您可以使用status
,description
(可选)定义Response
对象
header
(可选)和Resource
/ListResource
对象作为body
(可选)。
list_response=Response(status=200,description='Here is your orders list.',body=list_resource)detail_response=Response(status=200,description='Here is your order.',body=resource)error_response=Response(status=404,resource=error_resource,headers=[('Content-type':'application-json')])
…以及具有verb
、description
、header
(可选)和Resource
/ListResource
的Request
对象。
对象为payload
。
get_request=Request(verb=verbs.GET)
Action
对您的请求和在描述参数中传递的指定操作的响应列表进行分组。
list_action=Action(description='Returns a list of resources.',request=get_request,responses=[error_response,list_response])detail_action=Action(description='Returns a resource based on its code.',request=get_request,responses=[error_response,detail_response])
action对象和pactum中的所有其他元素一样,接收一个描述字符串
设置.__doc__
属性并可以是类的docstring
如果对象是由类定义定义的。
路由可以在http路径中有一个操作列表。
classOrderListRoute(Route):path='/orders'actions=[list_action]list_route=OrderListRoute()detail_route=OrderRoute(path='/orders/{code}',actions=detail_action)
您的路由可以在api版本中分组。
classV1(Version):name='V1'routes=[list_route,detail_route]v1=V1()
然后你可以定义你的api。;)
classOrdersAPI(API):name='Orders API'versions=[v1]api=OrdersAPI()
很高兴并准备好将您的规范导出到您想要的任何格式。
导出到OpenAPI规范。
pactum有一个命令将您的规范导出到openapi。您可以使用:
pactum-openapi <spec_file.py> <output_file> [--format=<json or yaml>]
通往版本1的道路。
- []测试元素。接受(访问者)方法。
- []支持版本选择器(版本应在http头、路径或自定义字段上指定)
- [X]稳定我们处理路径参数的方式。
- []支持授权和身份验证规范。
- []支持扩展。
- []行为