encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-09-21 03:19:00 +03:00
Code Issues Packages Projects Releases Wiki Activity

Allowed customising API documentation code samples (#5752)

Browse Source 
* Allowed additional languages in API documentation

* Documented renderer_classes parameter and customising languages.
This commit is contained in:
Carlton Gibson 2018-01-25 09:39:03 +01:00 committed by GitHub
parent 588b61e171
commit a540acdc95
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 49 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/topics/documenting-your-api.md
View File

@ -107,6 +107,7 @@ The `rest_framework.documentation` module provides three helper functions to hel
* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`.
#### `get_docs_view`
@ -117,7 +118,8 @@ The `rest_framework.documentation` module provides three helper functions to hel
* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`.
* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats.
#### `get_schemajs_view`
@ -130,6 +132,25 @@ The `rest_framework.documentation` module provides three helper functions to hel
* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
### Customising code samples
The built-in API documentation includes automatically generated code samples for
each of the available API client libraries.
You may customise these samples by subclassing `DocumentationRenderer`, setting
`languages` to the list of languages you wish to support:
from rest_framework.renderers import DocumentationRenderer
class CustomRenderer(DocumentationRenderer):
languages = ['ruby', 'go']
For each language you need to provide an `intro` template, detailing installation instructions and such,
plus a generic template for making API requests, that can be filled with individual request details.
See the [templates for the bundled languages][client-library-templates] for examples.
---
## Third party packages
@ -138,11 +159,11 @@ There are a number of mature third-party packages for providing API documentatio
#### drf-yasg - Yet Another Swagger Generator
[drf-yasg][drf-yasg] is a [Swagger][swagger] generation tool implemented without using the schema generation provided
[drf-yasg][drf-yasg] is a [Swagger][swagger] generation tool implemented without using the schema generation provided
by Django Rest Framework.
It aims to implement as much of the [OpenAPI][open-api] specification as possible - nested schemas, named models,
response bodies, enum/pattern/min/max validators, form parameters, etc. - and to generate documents usable with code
It aims to implement as much of the [OpenAPI][open-api] specification as possible - nested schemas, named models,
response bodies, enum/pattern/min/max validators, form parameters, etc. - and to generate documents usable with code
generation tools like `swagger-codegen`.
This also translates into a very useful interactive documentation viewer in the form of `swagger-ui`:
@ -314,3 +335,4 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
[image-self-describing-api]: ../img/self-describing.png
[schemas-examples]: ../api-guide/schemas/#example
[metadata-docs]: ../api-guide/metadata/
[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs

11
rest_framework/documentation.py
View File

@ -11,8 +11,11 @@ def get_docs_view(
title=None, description=None, schema_url=None, public=True,
patterns=None, generator_class=SchemaGenerator,
authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES):
renderer_classes = [DocumentationRenderer, CoreJSONRenderer]
permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES,
renderer_classes=None):
if renderer_classes is None:
renderer_classes = [DocumentationRenderer, CoreJSONRenderer]
return get_schema_view(
title=title,
@ -51,7 +54,8 @@ def include_docs_urls(
title=None, description=None, schema_url=None, public=True,
patterns=None, generator_class=SchemaGenerator,
authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES):
permission_classes=api_settings.DEFAULT_PERMISSION_CLASSES,
renderer_classes=None):
docs_view = get_docs_view(
title=title,
description=description,
@ -60,6 +64,7 @@ def include_docs_urls(
patterns=patterns,
generator_class=generator_class,
authentication_classes=authentication_classes,
renderer_classes=renderer_classes,
permission_classes=permission_classes,
)
schema_js_view = get_schemajs_view(

2
rest_framework/renderers.py
View File

@ -830,6 +830,8 @@ class DocumentationRenderer(BaseRenderer):
return {
'document': data,
'langs': self.languages,
'lang_htmls': ["rest_framework/docs/langs/%s.html" % l for l in self.languages],
'lang_intro_htmls': ["rest_framework/docs/langs/%s-intro.html" % l for l in self.languages],
'code_style': pygments_css(self.code_style),
'request': request
}

6
rest_framework/templates/rest_framework/docs/document.html
View File

@ -8,9 +8,9 @@
{% endif %}
</div>
<div class="col-md-6 intro-code">
{% if 'shell' in langs %}{% include "rest_framework/docs/langs/shell-intro.html" %}{% endif %}
{% if 'python' in langs %}{% include "rest_framework/docs/langs/python-intro.html" %}{% endif %}
{% if 'javascript' in langs %}{% include "rest_framework/docs/langs/javascript-intro.html" %}{% endif %}
{% for html in lang_intro_htmls %}
{% include html %}
{% endfor %}
</div>
</div>
{% if document|data %}

1
rest_framework/templates/rest_framework/docs/index.html
View File

@ -51,6 +51,7 @@
$('#auth-control').children().removeClass('active');
$('#auth-control').find("[data-auth='session']").closest('li').addClass('active');
{% endif %}
$('pre.highlight').filter('[data-language="{{ langs | first }}"]').removeClass('hide');
</script>
</body>
</html>

2
rest_framework/templates/rest_framework/docs/langs/shell-intro.html
View File

@ -1,3 +1,3 @@
{% load rest_framework %}
<pre class="highlight shell" data-language="shell"><code>{% code bash %}# Install the command line client
<pre class="highlight shell hide" data-language="shell"><code>{% code bash %}# Install the command line client
$ pip install coreapi-cli{% endcode %}</code></pre>

2
rest_framework/templates/rest_framework/docs/langs/shell.html
View File

@ -1,5 +1,5 @@
{% load rest_framework %}
<pre class="highlight shell" data-language="shell"><code>{% code bash %}# Load the schema document
<pre class="highlight shell hide" data-language="shell"><code>{% code bash %}# Load the schema document
$ coreapi get {{ document.url }}{% if schema_format %} --format {{ schema_format }}{% endif %}
# Interact with the API endpoint

6
rest_framework/templates/rest_framework/docs/link.html
View File

@ -93,9 +93,9 @@
</div>
<div class="col-md-6 code-samples">
{% if 'shell' in langs %}{% include "rest_framework/docs/langs/shell.html" %}{% endif %}
{% if 'python' in langs %}{% include "rest_framework/docs/langs/python.html" %}{% endif %}
{% if 'javascript' in langs %}{% include "rest_framework/docs/langs/javascript.html" %}{% endif %}
{% for html in lang_htmls %}
{% include html %}
{% endfor %}
</div>
</div>

8
rest_framework/templates/rest_framework/docs/sidebar.html
View File

@ -31,12 +31,12 @@
</ul>
<li data-toggle="collapse" data-target="#language-control" class="collapsed">
<a><i class="fa fa-code fa-lg"></i> Source Code</a> <span id="selected-language">shell</span>
<a><i class="fa fa-code fa-lg"></i> Source Code</a> <span id="selected-language">{{ langs | first }}</span>
</li>
<ul class="sub-menu collapse out" id="language-control">
<li class="active"><a href="#" data-language="shell">shell</a></li>
<li><a href="#" data-language="javascript">javascript</a></li>
<li><a href="#" data-language="python">python</a></li>
{% for lang in langs %}
<li{% if loop.first %} class="active"{% endif %}><a href="#" data-language="{{ lang }}">{{ lang }}</a></li>
{% endfor %}
</ul>
</ul>