django-apiblueprint-view

使用Django模板即时渲染API蓝图

安装

1. pip install django-apiblueprint-view

2. 将项目添加到django设置中的INSTALLED_APPS

INSTALLED_APPS = [
    ...
    'apiblueprint_view',
]

用法

from apiblueprint_view.views import ApiBlueprintView

urlpatterns = [
    url(r'^docs/$', ApiBlueprintView.as_view(blueprint='/path/to/blueprint.apibp')),
]

样式

自定义HTML模板

定义一个自定义基本模板。它必须包含标签

{% include 'api_docs/docs_parent.html' %}

将其作为参数传递给ApiBlueprintView.as_view()。

from apiblueprint_view.views import ApiBlueprintView

urlpatterns = [
    url(r'^docs/$', ApiBlueprintView.as_view(
        blueprint='/path/to/blueprint.apibp',
        template_name='my_base_template.html'
    )),
]

自定义CSS

ApiBlueprintView.as_view()可以接受一个描述要附加到渲染HTML标签的自定义CSS类的styles字典。例如

from apiblueprint_view.views import ApiBlueprintView

urlpatterns = [
    url(r'^docs/$', ApiBlueprintView.as_view(
        blueprint='/path/to/blueprint.apibp',
        template_name='my_base_template.html',
        styles={
            'action': {'class': 'foo bar'},
            'method': {'class': 'baz'}
        }
    )),
]

以下键是有效的。所有键都是可选的

• 'action'：API操作的容器<div>
• 'action_transaction'：HTTP事务（请求和响应）的容器<div>
• 'action_request'：HTTP请求的容器<div>
• 'action_response'：HTTP响应的容器<div>
• 'action_schema'：HTTP请求或响应模式的容器<div>
• 'action_headers'：HTTP请求或响应头部的容器<div>
• 'action_body'：HTTP请求或响应体的容器<div>
• 'action_example'：API操作示例URL的容器<div>
• 'description'：描述动作、资源、请求、响应等的文本的容器<div>
• 'parameters'：参数列表的容器 <div>
• 'method'：包含 HTTP 方法的通用 <span>
• 'method_CONNECT'：包含文本 CONNECT 的 <span>
• 'method_DELETE'：包含文本 DELETE 的 <span>
• 'method_GET'：包含文本 GET 的 <span>
• 'method_HEAD'：包含文本 HEAD 的 <span>
• 'method_OPTIONS'：包含文本 OPTIONS 的 <span>
• 'method_PATCH'：包含文本 PATCH 的 <span>
• 'method_POST'：包含文本 POST 的 <span>
• 'method_PUT'：包含文本 PUT 的 <span>
• 'method_TRACE'：包含文本 TRACE 的 <span>
• 'resource'：API 资源的容器 <div>
• 'resource_group'：API 资源组的容器 <div>

可以使用 Highlight.js 添加语法高亮显示

包含文件

您可以通过使用指向包含文件相对路径的 include 指令，在蓝图文件中包含其他文件。包含的文件可以包含其他文件，因此请小心处理循环引用。

<!-- include(filename.md) -->

此语法不是 API Blueprint 规范的一部分，但也被一些其他工具支持，例如：aglio。

如果您的应用程序渲染用户提供的文本，include 指令可能会引入远程文件包含或目录遍历漏洞。有一些设置可以帮助缓解此问题。在 django 设置中将 APIBP_PROCESS_INCLUDES = False 设置为完全忽略 include 指令（默认为 True）。还有允许包含的文件类型白名单。默认白名单是 ['.md', '.apibp', '.json']，但可以通过在 django 设置中将 APIBP_INCLUDE_WHITELIST 设置为允许扩展名的列表来覆盖它。