Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chris48s/django-apiblueprint-view
📚 Render API Blueprints on-the-fly using Django templates
https://github.com/chris48s/django-apiblueprint-view
api-blueprint django-apps documentation
Last synced: 10 days ago
JSON representation
📚 Render API Blueprints on-the-fly using Django templates
- Host: GitHub
- URL: https://github.com/chris48s/django-apiblueprint-view
- Owner: chris48s
- License: mit
- Created: 2017-07-30T20:51:14.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-10-12T20:14:41.000Z (24 days ago)
- Last Synced: 2024-10-13T20:10:02.579Z (23 days ago)
- Topics: api-blueprint, django-apps, documentation
- Language: Python
- Homepage: https://pypi.org/pypi/django-apiblueprint-view/
- Size: 602 KB
- Stars: 15
- Watchers: 2
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# django-apiblueprint-view
[](https://github.com/chris48s/django-apiblueprint-view/actions/workflows/test.yml)
[](https://codecov.io/gh/chris48s/django-apiblueprint-view)
Render [API Blueprints](https://apiblueprint.org/) on-the-fly using Django templates
## Installation
1. `pip install django-apiblueprint-view`
2. Add to `INSTALLED_APPS` in django settings:
```python
INSTALLED_APPS = [
...
'apiblueprint_view',
]
```
## Usage
```python
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.
```python
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:
```python
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 `
` for an API action
* `'action_transaction'`: Container `` for a HTTP transaction (request and response)
* `'action_request'`: Container `` for a HTTP request
* `'action_response'`: Container `` for a HTTP response
* `'action_schema'`: Container `` for a HTTP request or response schema
* `'action_headers'`: Container `` for HTTP request or response headers
* `'action_body'`: Container `` for a HTTP request or response body
* `'action_example'`: Container `` for an API action example URL
* `'description'`: Container `` for some text describing an action, resource, request, response, etc
* `'parameters'`: Container `` for a list of parameters
* `'method'`: Generic `` containing an HTTP method
* `'method_CONNECT'`: `` containing the text `CONNECT`
* `'method_DELETE'`: `` containing the text `DELETE`
* `'method_GET'`: `` containing the text `GET`
* `'method_HEAD'`: `` containing the text `HEAD`
* `'method_OPTIONS'`: `` containing the text `OPTIONS`
* `'method_PATCH'`: `` containing the text `PATCH`
* `'method_POST'`: `` containing the text `POST`
* `'method_PUT'`: `` containing the text `PUT`
* `'method_TRACE'`: `` containing the text `TRACE`
* `'resource'`: Container `` for an API resource
* `'resource_group'`: Container `` for an API resource group
[Highlight.js](https://highlightjs.org/) 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.
```
```
This syntax is not a part of the API Blueprint spec, but is also supported in some other tools e.g: [aglio](https://github.com/danielgtaylor/aglio#including-files).
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.