Render API Blueprints on-the-fly using Django templates
Project description
Render API Blueprints on-the-fly using Django templates
Installation
django-apiblueprint-view uses the Drafter C library for API Blueprint parsing. Install it using:
wget https://github.com/apiaryio/drafter/releases/download/v3.2.7/drafter-v3.2.7.tar.gz tar xvzf drafter-v3.2.7.tar.gz cd drafter-v3.2.7 ./configure --shared make libdrafter sudo cp build/out/Release/lib.target/libdrafter.so /usr/lib/libdrafter.so sudo cp src/drafter.h /usr/include/drafter/drafter.h
pip install django-apiblueprint-view
Add to INSTALLED_APPS in django settings:
INSTALLED_APPS = [
...
'apiblueprint_view',
]
Platform Support
django-apiblueprint-view is tested under: * Python 3.4, 3.5 and 3.6 * Django 1.8, 1.9, 1.10, 1.11 and 2.0
Usage
from apiblueprint_view.views import ApiBlueprintView
urlpatterns = [
url(r'^docs/$', ApiBlueprintView.as_view(blueprint='/path/to/blueprint.apibp')),
]
Styling
Custom HTML Template
Define a custom base template. It must include the tag
{% include 'api_docs/docs_parent.html' %}
Pass it into ApiBlueprintView.as_view() as a parameter.
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.as_view() may accept a styles dictionary describing custom CSS classes which should be attached to rendered HTML tags. For example:
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 text CONNECT
'method_DELETE': <span> containing the text DELETE
'method_GET': <span> containing the text GET
'method_HEAD': <span> containing the text HEAD
'method_OPTIONS': <span> containing the text OPTIONS
'method_PATCH': <span> containing the text PATCH
'method_POST': <span> containing the text POST
'method_PUT': <span> containing the text PUT
'method_TRACE': <span> containing the text TRACE
'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.
Licensing
django-apiblueprint-view is made available under the MIT License
Development
Build and install locally:
python setup.py sdist pip install --upgrade dist/django-apiblueprint-view-x.y.z.tar.gz
Run the tests locally:
pip install -r testing_requirements.txt ./run_tests.py
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 Distribution
Hashes for django-apiblueprint-view-1.1.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7c65b596d7d61811edcf69035da99197cad062a14034649835064cebf2b56ee8 |
|
MD5 | ec1073943039c27a6ea40100bbcab513 |
|
BLAKE2b-256 | 2175e5c206e3cfee258f481f43d909d11c26afd16eadb65f58221ad88b8cb21d |