用于openapi规范生成的金字塔插件
pyramid-apispec的Python项目详细描述
棱锥图APISPEC
棱锥体apispec允许您创建OpenAPI specification file 使用apispec和使用 Swagger UI为您的Pyramid项目 应用程序及其marshmallow模式。
安装
pip install pyramid_apispec
基本用法
通过运行:
pip install -e '.[demo]'
python demo/app.py
然后,您可以访问位于http://0.0.0.0:6543/api-explorer的api资源管理器页面。
示例
访问generated documentation here (请注意,实际的rest api在github页面中不起作用)
提示路线及其视图:
@view_config(route_name='foo_route', renderer='json')
def foo_view():
"""A greeting endpoint.
---
x-extension: value
get:
description: some description
responses:
200:
description: response for 200 code
schema:
$ref: #/definitions/BarBodySchema
"""
return 'hi'
将规范呈现为json响应:
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from pyramid_apispec.helpers import add_pyramid_paths
@view_config(route_name='openapi_spec', renderer='json')
def api_spec(request):
spec = APISpec(
title='Some API',
version='1.0.0',
plugins=[MarshmallowPlugin()],
)
# using marshmallow plugin here
spec.definition('SomeFooBody', schema=MarshmallowSomeFooBodySchema)
# inspect the `foo_route` and generate operations from docstring
add_pyramid_paths(spec, 'foo_route', request=request)
# inspection supports filtering via pyramid add_view predicate arguments
add_pyramid_paths(
spec, 'bar_route', request=request, request_method='post')
return spec.to_dict()
添加API资源管理器视图
为了补充规范文件的生成,这个包还可以提供一个api资源管理器 对于应用程序的api,通过swagger ui项目:
config.include('pyramid_apispec.views')
config.add_route("openapi_spec", "/openapi.json")
config.pyramid_apispec_add_explorer(
spec_route_name='openapi_spec')
默认情况下,您需要传递服务于openapi的视图的路由名称
应用程序中的规范。如果需要,可以指定棱锥体permission
或
自定义可调用(script_generator
参数)以覆盖默认javascript
swagger ui的配置。
资源管理器的默认url是/api-explorer
。此设置受控制
通过explorer_route_path
参数-路由被注册为pyramid_apispec.api_explorer_path
。
运行测试
pip install -e '.[dev]'
tox