Render API Blueprints on-the-fly using Django templates
Project description
django-apiblueprint-view
Render API Blueprints on-the-fly using Django templates
Installation
-
pip install django-apiblueprint-view
-
Add to
INSTALLED_APPS
in django settings:
INSTALLED_APPS = [
...
'apiblueprint_view',
]
Basic Usage
from apiblueprint_view.views import ApiBlueprintView
urlpatterns = [
url(r'^docs/$', ApiBlueprintView.as_view(blueprint='/path/to/blueprint.apibp')),
]
ApiBlueprintView
has 4 properties which may be passed as params to .as_view()
as parameters, or defined as class properties:
from apiblueprint_view.views import ApiBlueprintView
class ApiDocsView(ApiBlueprintView):
blueprint = 'path/to/blueprint.apibp' # blueprint to render
drafter_path = 'path/to/libdrafter.so' # custom drafter library
template_name = 'base_template.html' # template to render with
styles = { # custom CSS clases
'resource': {'class': 'card'},
'resource_group': {'class': 'card'},
}
urlpatterns = [
url(r'^docs/$', ApiDocsView.as_view()),
]
Drafter
django-apiblueprint-view
uses the Drafter C library for API Blueprint parsing. It is compatible with any Drafter >=4.0.0,<6.0.0. By default, a manylinux drafter 4.1.0 shared object is bundled with the package, but it is also possible to use an external drafter library by setting drafter_path
. This is necessary if you want to use a different version of drafter or use this library on Windows/Mac.
# Use the vendored shared object (drafter 4.1.0/manylinux).
ApiBlueprintView.as_view(blueprint='/path/to/blueprint.apibp')
# Use drafter at this specific path.
ApiBlueprintView.as_view(
blueprint='/path/to/blueprint.apibp',
drafter_path='/path/to/libdrafter.dylib'
)
# Search for a global `libdrafter` using `ctypes.util.find_library()`.
ApiBlueprintView.as_view(
blueprint='/path/to/blueprint.apibp',
drafter_path=None
)
Styling
Custom HTML Template
Define a custom base template. It must include the tag
{% include 'api_docs/docs_parent.html' %}
Set it using template_name
.
from apiblueprint_view.views import ApiBlueprintView
urlpatterns = [
url(r'^docs/$', ApiBlueprintView.as_view(
blueprint='/path/to/blueprint.apibp',
template_name='my_base_template.html'
)),
]
Custom CSS
ApiBlueprintView may accept a styles
dictionary describing custom CSS classes which should be attached to rendered HTML tags.
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'}
}
)),
]
The following keys are valid. All keys are optional:
'action'
: Container<div>
for an API action'action_transaction'
: Container<div>
for a HTTP transaction (request and response)'action_request'
: Container<div>
for a HTTP request'action_response'
: Container<div>
for a HTTP response'action_schema'
: Container<div>
for a HTTP request or response schema'action_headers'
: Container<div>
for HTTP request or response headers'action_body'
: Container<div>
for a HTTP request or response body'action_example'
: Container<div>
for an API action example URL'description'
: Container<div>
for some text describing an action, resource, request, response, etc'parameters'
: Container<div>
for a list of parameters'method'
: Generic<span>
containing an HTTP method'method_CONNECT'
:<span>
containing the textCONNECT
'method_DELETE'
:<span>
containing the textDELETE
'method_GET'
:<span>
containing the textGET
'method_HEAD'
:<span>
containing the textHEAD
'method_OPTIONS'
:<span>
containing the textOPTIONS
'method_PATCH'
:<span>
containing the textPATCH
'method_POST'
:<span>
containing the textPOST
'method_PUT'
:<span>
containing the textPUT
'method_TRACE'
:<span>
containing the textTRACE
'resource'
: Container<div>
for an API resource'resource_group'
: Container<div>
for an API resource group
Highlight.js can be used to add syntax highlighting
Including Files
You can include other files in your blueprint by using an include directive with a path to the included file relative to the current file's directory. Included files can include other files, so be careful of circular references.
<!-- include(filename.md) -->
This syntax is not a part of the API Blueprint spec, but is also supported in some other tools e.g: aglio.
The include directive has the potential to introduce remote file inclusion or directory traversal vulnerabilities if your application renders user-supplied content. There are a couple of settings to help mitigate this. Set APIBP_PROCESS_INCLUDES = False
in your django settings to completely ignore include directives (the default is True
). There is also a whitelist of allowed file types to include. The default whitelist is ['.md', '.apibp', '.json']
but this can be overridden by setting APIBP_INCLUDE_WHITELIST
to a list of allowed extensions in your django settings.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for django_apiblueprint_view-3.0.0b5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2e6728182c3dfa6c39bda8e6309b7ee0708b6fce69c2463ad4d15e997b022890 |
|
MD5 | 25666f7a6723bc063b6fd3296b373b8c |
|
BLAKE2b-256 | b38cb0a98a7be50cae9eb3f775681282c2a4b917a2ae1a6f447a4309086a34fe |