diff --git a/docs/img/api-docs.gif b/docs/img/api-docs.gif new file mode 100644 index 000000000..6da560b7e Binary files /dev/null and b/docs/img/api-docs.gif differ diff --git a/docs/img/api-docs.png b/docs/img/api-docs.png new file mode 100644 index 000000000..939075a89 Binary files /dev/null and b/docs/img/api-docs.png differ diff --git a/docs/index.md b/docs/index.md index 87ef0e9e3..f6f459083 100644 --- a/docs/index.md +++ b/docs/index.md @@ -279,7 +279,7 @@ Send a description of the issue via email to [rest-framework-security@googlegrou ## License -Copyright (c) 2011-2016, Tom Christie +Copyright (c) 2011-2017, Tom Christie All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/docs/topics/3.6-announcement.md b/docs/topics/3.6-announcement.md index f5aeab3e8..91c939ae0 100644 --- a/docs/topics/3.6-announcement.md +++ b/docs/topics/3.6-announcement.md @@ -19,11 +19,21 @@ # Django REST framework 3.6 +The 3.6 release adds two major new features to REST framework. + +1. Built-in interactive API documentation support. +2. A new JavaScript client library. + + + +*Above: The interactive API documentation.* + --- ## Funding -The 3.6 release would not have been possible without our [collaborative funding model][funding]. +The 3.6 release would not have been possible without our [backing from Mozilla](mozilla-grant.md) to the project, and our [collaborative funding model][funding]. + If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by **[signing up for a paid plan][funding]**. @@ -40,24 +50,141 @@ we strongly encourage you to invest in its continued development by *Many thanks to all our [sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://hello.machinalis.co.uk/), [Rollbar](https://rollbar.com), and [MicroPyramid](https://micropyramid.com/django-rest-framework-development-services/).* +--- + +## Interactive API documentation + +REST framework's new API documentation supports a number of features: + +* Live API interaction. +* Support for various authentication schemes. +* Code snippets for the Python, JavaScript, and Command Line clients. + +To install the API documentation, you'll need to include it in your projects URLconf: + + from rest_framework.documentation import include_docs_urls + + API_TITLE = 'API title' + API_DESCRIPTION = '...' + + urlpatterns = [ + ... + url(r'^docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION)) + ] + +Once installed you should see something a little like this: + + + +We'll likely be making further refinements to the API documentation over the +coming weeks. Keep in mind that this is a new feature, and please do give +us feedback if you run into any issues or limitations. + +For more information on documenting your API endpoints see the ["Documenting your API"][api-docs] section. --- -## API documentation +## JavaScript client library -... +The JavaScript client library allows you to load an API schema, and then interact +with that API at an application layer interface, rather than constructing fetch +requests explicitly. -## JavaScript Client +Here's a brief example that demonstrates: -... +* Loading the client library and schema. +* Instantiating an authenticated client. +* Making an API request using the client. + +**index.html** + + +
+ + + + + + +The JavaScript client library supports various authentication schemes, and can be +used by your project itself, or as an external client interacting with your API. + +The client is not limited to usage with REST framework APIs, although it does +currently only support loading CoreJSON API schemas. Support for Swagger and +other API schemas is planned. + +For more details see the [JavaScript client library documentation][js-docs]. + +## Authentication classes for the Python client library + +Previous authentication support in the Python client library was limited to +allowing users to provide explicit header values. + +We now have better support for handling the details of authentication, with +the introduction of the `BasicAuthentication`, `TokenAuthentication`, and +`SessionAuthentication` schemes. + +You can include the authentication scheme when instantiating a new client. + + auth = coreapi.auth.TokenAuthentication(scheme='JWT', token='xxx-xxx-xxx') + client = coreapi.Client(auth=auth) + +For more information see the [Python client library documentation][py-docs]. --- ## Deprecations -... +### Generating schemas from Router + +The 3.5 "pending deprecation" of router arguments for generating a schema view, such as `schema_title`, `schema_url` and `schema_renderers`, have now been escalated to a +"deprecated" warning. + +Instead of using `DefaultRouter(schema_title='Example API')`, you should use the `get_schema_view()` function, and include the view explicitly in your URL conf. + +### DjangoFilterBackend + +The 3.5 "pending deprecation" warning of the built-in `DjangoFilterBackend` has now +been escalated to a "deprecated" warning. + +You should change your imports and REST framework filter settings as follows: + +* `rest_framework.filters.DjangoFilterBackend` becomes `django_filters.rest_framework.DjangoFilterBackend`. +* `rest_framework.filters.FilterSet` becomes `django_filters.rest_framework.FilterSet`. --- +## What's next + +There are likely to be a number of refinements to the API documentation and +JavaScript client library over the coming weeks, which could include some of the following: + +* Support for private API docs, requiring login. +* File upload and download support in the JavaScript client & API docs. +* Comprehensive documentation for the JavaScript client library. +* Automatically including authentication details in the API doc code snippets. +* Adding authentication support in the command line client. +* Support for loading Swagger and other schemas in the JavaScript client. +* Improved support for documenting parameter schemas and response schemas. +* Refining the API documentation interaction modal. + +Once work on those refinements is complete, we'll be starting feature work +on realtime support, for the 3.7 release. + [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors [funding]: funding.md +[api-docs]: documenting-your-api.md +[js-docs]: api-clients.md#javascript-client-library +[py-docs]: api-clients.md#python-client-library diff --git a/docs/topics/api-clients.md b/docs/topics/api-clients.md index 17721d782..6e0df69e5 100644 --- a/docs/topics/api-clients.md +++ b/docs/topics/api-clients.md @@ -240,9 +240,59 @@ Once we have a `Client` instance, we can fetch an API schema from the network. schema = client.get('https://api.example.org/') The object returned from this call will be a `Document` instance, which is -the internal representation of the interface that we are interacting with. +a representation of the API schema. -Now that we have our schema `Document`, we can now start to interact with the API: +## Authentication + +Typically you'll also want to provide some authentication credentials when +instantiating the client. + +#### Token authentication + +The `TokenAuthentication` class can be used to support REST framework's built-in +`TokenAuthentication`, as well as OAuth and JWT schemes. + + auth = coreapi.auth.TokenAuthentication( + scheme='JWT' + token='%s
'
- LANG_TAG = ' class="highlight %s"'
-
-
-class FencedCodeExtension(markdown.Extension):
-
- def extendMarkdown(self, md, md_globals):
- """ Add FencedBlockPreprocessor to the Markdown instance. """
- md.registerExtension(self)
-
- md.preprocessors.add('fenced_code_block',
- CustomFencedBlockPreprocessor(md),
- ">normalize_whitespace")
-
-
@register.tag(name='code')
def highlight_code(parser, token):
code = token.split_contents()[-1]
@@ -56,14 +38,8 @@ class CodeNode(template.Node):
self.nodelist = code
def render(self, context):
- from pygments import highlight
- from pygments.lexers import get_lexer_by_name
- from pygments.formatters import HtmlFormatter
- body = self.nodelist.render(context)
- lexer = get_lexer_by_name(self.lang, stripall=False)
- formatter = HtmlFormatter(nowrap=True, style=self.style)
- code = highlight(body, lexer, formatter)
- return code
+ text = self.nodelist.render(context)
+ return pygments_highlight(text, self.lang, self.style)
@register.filter()
@@ -92,7 +68,9 @@ def form_for_link(link):
@register.simple_tag
def render_markdown(markdown_text):
- return markdown.markdown(markdown_text, extensions=[FencedCodeExtension(), "tables"])
+ if not markdown:
+ return markdown_text
+ return markdown.markdown(markdown_text)
@register.simple_tag
diff --git a/tests/test_filters.py b/tests/test_filters.py
index 7db5da63f..1b6f6f273 100644
--- a/tests/test_filters.py
+++ b/tests/test_filters.py
@@ -180,8 +180,8 @@ class IntegrationTestFiltering(CommonFilteringTestCase):
assert response.status_code == status.HTTP_200_OK
assert response.data == self.data
- self.assertTrue(issubclass(w[-1].category, PendingDeprecationWarning))
- self.assertIn("'rest_framework.filters.DjangoFilterBackend' is pending deprecation.", str(w[-1].message))
+ self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+ self.assertIn("'rest_framework.filters.DjangoFilterBackend' is deprecated.", str(w[-1].message))
@unittest.skipUnless(django_filters, 'django-filter not installed')
def test_no_df_deprecation(self):