Skip to main content

Render API Blueprints on-the-fly using Django templates

Project description

django-apiblueprint-view

Build Status Coverage Status PyPI Version License Python Support Django Support Code style: black

Render API Blueprints on-the-fly using Django templates

Installation

  1. pip install django-apiblueprint-view

  2. Add to INSTALLED_APPS in django settings:

INSTALLED_APPS = [
    ...
    'apiblueprint_view',
]

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-apiblueprint-view, version 2.3.0
Filename, size File type Python version Upload date Hashes
Filename, size django_apiblueprint_view-2.3.0-py3-none-any.whl (1.1 MB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django_apiblueprint_view-2.3.0-py3-none-manylinux1_x86_64.whl (1.1 MB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page