chris48s / django-apiblueprint-view

📚 Render API Blueprints on-the-fly using Django templates

django-apiblueprint-view

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.

django-apiblueprint-view's Issues

Add more test cases

Core rendering is well covered but there are a several cases which are missing test coverage:

• Included files added in #10
• Host is set added in 8e57101
• Custom styles applied

Add classes for HTTP status code categories

It might be nice to define custom styles for 1xx, 2xx, 3xx, 4xx, 5xx codes. Add classes we can hook into for this

2.0.1 removes some useful whitespace

e.g:

before:

after:

---

before:

after:

Upgrade to drafter 4

https://github.com/apiaryio/drafter/releases/tag/v4.1.0

Building example URL doesn't support {?foo} or {foo,bar}

Param substitution fails if format is {?foo} or {foo,bar}

e.g: https://github.com/apiaryio/api-blueprint/blob/master/examples/12.%20Advanced%20Action.md#tasks-taskstasksstatuspriority

Longer-term solution to building drafter 3.2.7

While this library itself is python >=3.7, the configure script for drafter 3.2.7 requires python2.
Getting it to run on python3 is not just a matter of patching the configure script itself. If you do that, you start hitting errors on ext/snowcrash/tools/gyp/gyp_main.py, etc. There is a fairly substantial chunk of vendoered python 2 code to deal with there.

I've solved this for the medium-term by pinning the CI build to run on ubuntu-20.04 in 847b3b3 but I'm going to need to find some kind of longer-term solution to this because:

1. That option will be removed one day. GitHub removed the ubuntu-18.04 image in Dec 2022, for example
2. At some point I'll also need a solution to this for local development

I'll need to either find a way to either build libdrafter 3.2.7 with python3 for the configure step or build the lib with python2 in CI.

Installing python2 in CI is probably easier. It is no longer an option with actions/setup-python so I'd probably have to install it with deadsnakes PPA or something. The other option might be to do the compile step on a custom docker image with

runs-on: ubuntu-latest
container:
  image: python:2.7

(untested), save the shared object as a build artifact and then grab the artifact and do everything else on a sensible modern platform. None of this would enable me to build locally, but I could always grab the shared object from CI for local dev.

Audit/repair wheel independently of publishing to PyPI

Discovering/debugging issues with this is a pain point because by default it only runs on a tagged commit to master. It would be useful to separate the process of building and publishing so I become aware of problems before the last possible moment.

Display URL param details in rendered HTML

See https://github.com/apiaryio/api-blueprint/blob/master/examples/07.%20Parameters.md

Test on django 3.2, review django version support

When django 3.2 is out (April 2021), test on it + review these:

django-apiblueprint-view/.github/workflows/test.yml

Line 10 in 7447069

django-version: ['>=1.11,<1.12', '>=2.1,<2.2', '>=2.2,<2.3', '>=3.0,<3.1']

django-apiblueprint-view/pyproject.toml

Lines 10 to 16 in 7447069

	classifiers = [
	"Framework :: Django",
	"Framework :: Django :: 1.11",
	"Framework :: Django :: 2.1",
	"Framework :: Django :: 2.2",
	"Framework :: Django :: 3.0",
	]

django-apiblueprint-view/pyproject.toml

Line 23 in 7447069

Django = ">=1.11,<4.0"

Make package easier to install

It would be nice if manually compiling drafter wasn't part of the installation process.

At the moment django-apiblueprint-view is packaged as a source distribution. I've not done it before, but I think it is possible to build a binary distribution such that the C dependencies get bundled with the python code.

I think the tradeoff of that may be that you lose cross-platform compatibility? It would be useful to maintain that.

I think it is also possible to build a package that bundles the C source and then compiles it as part of the pip install as long as the target install platform has a C compiler.

I will need to do some reading on this...

Support alpine linux

Is it possible that this package doesn't work when running on alpine linux because of the special handling of drafter?

I'm getting a Fatal Python error: Segmentation fault when trying to render a blueprint.

Dependabot can't resolve your Python dependency files

Dependabot can't resolve your Python dependency files.

As a result, Dependabot couldn't update your dependencies.

The error Dependabot encountered was:

Creating virtualenv django-apiblueprint-view-Qs2LqkPf-py3.8 in /home/dependabot/.cache/pypoetry/virtualenvs
Updating dependencies
Resolving dependencies...

[PackageNotFound]
Package coveralls (1.11.1) not found.

If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.

View the update logs.

Switch to codecov

Invoking coveralls with COVERALLS_REPO_TOKEN won't produce coverage reports on PRs made from a fork. Switching to codecov will allow me to use a GH action to upload a report without needing a custom token.

Question about possible code exploit

From the README:

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.

And the line in the code that parses includes looks like this:

include_path = os.path.join(os.path.dirname(self.blueprint), match)

What if the value of match there is ../../../etc/passwd? Is there some sort of sanity check that makes sure this code can't be made to include arbitrary files on the file system?

It might be best to use Django's safe_join and raise a SuspiciousOperation exception if the absolute path of the included file is outside of the django project's directory.

This might be built in to drafter, but it's not obvious that a) it is and b) it can be trusted to be there forever.

Build mac-compatible wheels

More work to be done on this, but..

see notes in #179 (comment)

and proof of concept in 476ba1d

Support APIBP includes

Drafter doesn't support this natively, but some APIBP tools support includes using this syntax:

<!-- include(myfile.apibp) -->

This is really useful.

Create a pre-parser step which substitutes each include statement for the relevant file contents before passing to Drafter

Support local anchor links

Linking to [foo](#bar) doesn't work as intended. |markdown isn't processing it correctly here

Is this relevant? trentm/python-markdown2#232

Better styling/theming docs

Provide better/more concrete examples of custom HTML template and CSS

Incorrect URLs in resource with state transition

https://github.com/apiaryio/api-blueprint/blob/master/examples/12.%20Advanced%20Action.md

https://github.com/chris48s/django-apiblueprint-view/blob/master/apiblueprint_view/tests/test_12_advanced_action.py