Schemas & client libraries. #4179

tomchristie · 2016-06-08T13:30:07Z

Support for schema generation & dynamic client libraries.

See the new tutorial section, schema documentation, and api client documentation.

Needed to complete tutorial 7:

Graceful behavior with or without Core API installed.
Add --auth basic support to Core API.
Check permissions on schema generation.
Include pagination parameters in automatic schemas.

Other work as part of this, prior to 3.4.0 release.

Include filter parameters in automatic schemas.
Schema documentation.
Handle Document, Error and Link in JSON renderer?
Handle ListSerializer and other non-form.
Handle multipart vs json and/or other encodings.
Tests.
Handle text downloads.
Client library documentation.
Add coreapi to list of optional packages on homepage.

Moved to separate tickets:

Easier overrides on SchemaGenerator
Document using OpenAPI and other schema formats.
Move alternate formats in coreapi into separate packages. (HTML, OpenAPI, HyperSchema, HAL...)

Deferred:

~~Handle binary downloads.~~ Not strictly required for 3.4
~~Use id not pk in schema representations or change serializer representations?~~ Not strictly required for 3.4
~~Add to quickstart~~ Not strictly required for 3.4

…stalled.

kevin-brown · 2016-06-15T15:51:05Z

rest_framework/routers.py


            def get(self, request, *args, **kwargs):
+                if request.accepted_renderer.format == 'corejson':


Is there any reason why this couldn't be brought into the CoreJSONRenderer?

The problem is less what to do with CoreJSONRenderer and more about making sure that we preserve the behavior of that view for anything that isn't a schema renderer.

(Also I'd consider that part still slightly in flux - clearly needs refinement)

making sure that we preserve the behavior of that view for anything that isn't a schema renderer

Right, my main concern with that line (which I'm sure will probably change another few times before this is merged) is that it's hard-coding corejson as the only renderer with schema support.

Also I'd consider that part still slightly in flux - clearly needs refinement

Definitely understandable.

kevin-brown · 2016-06-15T16:05:36Z

rest_framework/renderers.py

@@ -790,3 +791,17 @@ def render(self, data, accepted_media_type=None, renderer_context=None):
                    "test case." % key
                )
        return encode_multipart(self.BOUNDARY, data)
+
+
+class CoreJSONRenderer(BaseRenderer):


There was a move in 3.1 to remove features which had third-party dependencies from the core and put them into third-party packages that were still highly visible. See django-rest-framework-xml, django-rest-framework-yaml, and django-rest-framework-oauth for examples.

Is that still something we are pushing for?

Kinda. I see coreapi as a foundational thing here, so it's a bit different.

The various types of schema and docs that you can use it to generate will be third party, yup.
So eg we can have third party packages for schema formats: Swagger / API Blueprint / JSON Hyperschema, for docs templates driven by a coreapi.Document object, and for various hypermedia styles.

Using coreapi ensures that we're able to provide a common interface for all of those, so I don't have any great issues with pulling it in. If it's in core, then we're making the promise that it's an interface that is available to third-party devs, which should help drive folks making schema renderers / hypermedia renderers and docs renderers. Having said that, we could push for it to be third-party, if we wanted to, so I might be open to discussion.

foresmac · 2016-07-01T16:21:07Z

docs/api-guide/schemas.md

+
+    router = DefaultRouter(schema_title='Server Monitoring API')
+
+The schema will be included in by the root URL, `/`, and presented to clients


"included in by" seems confusing. Maybe take out the "by"?

Good catch, that's a typo.

tomchristie · 2016-07-04T15:49:04Z

Remaining issues have now been split out into individual tickets.
Plan is to prepare up a 3.4.0 release, then resolve as many remaining tickets in the time remaining before Thursday 14th July, with a release planned on or before that date.

(Ensure it will be released prior to DjangoCon US, and give at least one clear working day to resolve any ciritical issues, post-release)

marcgibbons · 2016-07-04T16:25:08Z

💯

tomchristie · 2016-07-04T16:30:04Z

Yeah. Indeed.

kevin-brown · 2016-07-05T00:29:02Z

rest_framework/filters.py

@@ -127,6 +130,17 @@ def to_html(self, request, queryset, view):
        template = loader.get_template(self.template)
        return template_render(template, context)

+    def get_fields(self, view):
+        filter_class = getattr(view, 'filter_class', None)


Wouldn't it make more sense to use self.get_filter_class here?

Possibly, tho we don't actually have a queryset/model available to us at this point, so couldn't dynamically generate the filter class if none was set explicitly.

What are the problems with just calling view.get_queryset()?

Sure, that'd probably work okay.

DRF 3.4.7 is the same version run by edx/credentials. Release notes are at http://www.django-rest-framework.org/topics/release-notes/#34x-series. Highlights include: support for Django 1.10 (encode/django-rest-framework#4158 - sigh), support for schema generation (encode/django-rest-framework#4179 - required for newer versions of django-rest-swagger), and a change that prevents paginated views from re-running queries when count queries return 0 (encode/django-rest-framework#4201 - this explains the expected query count changes made in tests). LEARNER-1590

DRF 3.4.7 is the same version run by edx/credentials. Release notes are at http://www.django-rest-framework.org/topics/release-notes/#34x-series. Highlights include: - [Support for Django 1.10](encode/django-rest-framework#4158) - sigh - [Support for schema generation](encode/django-rest-framework#4179) - required for newer versions of django-rest-swagger - A [change](encode/django-rest-framework#4201) that prevents paginated views from re-running queries when count queries return 0 - this explains the expected query count changes made in tests LEARNER-1590

DRF 3.4.7 is the same version run by edx/credentials. Release notes are at http://www.django-rest-framework.org/topics/release-notes/#34x-series. Highlights include: 1. [Support for Django 1.10](encode/django-rest-framework#4158) - sigh 2. [Support for schema generation](encode/django-rest-framework#4179) - required for newer versions of django-rest-swagger 3. A change that [prevents paginated views from re-running queries](encode/django-rest-framework#4201) when count queries return 0 - this explains the expected query count changes made in tests LEARNER-1590

swehba · 2018-11-19T23:50:46Z

@tomchristie FYI, the links in your original comment at the top of this thread are broken.

Initial pass at schema support

bc836aa

tomchristie added the Enhancement label Jun 8, 2016

tomchristie added this to the 3.4.0 Release milestone Jun 8, 2016

tomchristie added 15 commits June 9, 2016 11:22

Add coreapi to optional requirements.

b64340b

Clean up test failures

c890ad4

Add missing newline

2d28390

Minor docs update

744dba4

Version bump for coreapi in requirements

56ece73

Catch SyntaxError when importing coreapi with python 3.2

99adbf1

Add --diff to isort

80c595e

Import coreapi from compat

47c7765

Fail gracefully if attempting to use schemas without coreapi being in…

29e228d

…stalled.

Tutorial updates

eeffca4

Docs update

6c60f58

Initial schema generation & first tutorial 7 draft

b7fcdd2

Spelling

2e60f41

Remove unused variable

2ffa145

Docs tweak

b709dd4

This was referenced Jun 10, 2016

REST framework 3.4 - Schema generation. marcgibbons/django-rest-swagger#453

Closed

Schema support in REST framework 3.4 manosim/django-rest-framework-docs#98

Open

tomchristie added 2 commits June 14, 2016 11:22

Merge branch 'master' into schema-support

474a23e

Added SchemaGenerator class

4822896

kevin-brown reviewed Jun 15, 2016
View reviewed changes

Fail gracefully if coreapi is not installed and SchemaGenerator is used

1f76cca

kevin-brown reviewed Jun 15, 2016
View reviewed changes

tomchristie mentioned this pull request Jun 17, 2016

Swagger 2.0 roadmap marcgibbons/django-rest-swagger#443

Closed

tomchristie added 3 commits June 21, 2016 16:59

Schema docs, pagination controls, filter controls

cad24b1

Resolve NameError

8fb2602

Add 'view' argument to 'get_fields()'

b438281

tomchristie added 3 commits June 29, 2016 17:22

Inital pass at API client docs

63e8467

Inital pass at API client docs

bdbcb33

More work towards client documentation

7236af3

foresmac reviewed Jul 1, 2016
View reviewed changes

tomchristie added 3 commits July 4, 2016 13:52

Add coreapi to optional packages list

89540ab

Clean up API clients docs

e3ced75

Resolve typo

12be5b3

tomchristie mentioned this pull request Jul 4, 2016

Schema & Hypermedia follow ups #4241

Closed

7 tasks

tomchristie merged commit 6ff9840 into master Jul 4, 2016

tomchristie deleted the schema-support branch July 4, 2016 15:38

This was referenced Jul 4, 2016

Easier overrides on SchemaGenerator #4242

Closed

Document using OpenAPI / other schema formats #4243

Closed

Move alternate formats in coreapi into separate packages. #4244

Closed

kevin-brown reviewed Jul 5, 2016
View reviewed changes

geekashu mentioned this pull request Jul 18, 2016

SchemaGenerator fails with message "object has no attribute 'get_serializer_class'" #4265

Closed

rpkilby mentioned this pull request Sep 22, 2016

Port get_schema_fields from DRF carltongibson/django-filter#492

Merged

pyup-bot mentioned this pull request Oct 22, 2016

Pin djangorestframework to latest version 3.5.1 wooyek/django-website-pro#16

Merged

pyup-bot mentioned this pull request Oct 30, 2016

Pin djangorestframework to latest version 3.5.1 Cyberbyte-Studios/Sensor-Portal#49

Merged

pyup-bot mentioned this pull request Feb 26, 2017

Pin djangorestframework to latest version 3.5.4 maidstone-hackspace/maidstone-hackspace-website#39

Merged

rlucioni mentioned this pull request Jul 12, 2017

Upgrade to DRF 3.4.7 openedx/course-discovery#1049

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Schemas & client libraries. #4179

Schemas & client libraries. #4179

tomchristie commented Jun 8, 2016 •

edited

kevin-brown Jun 15, 2016

tomchristie Jun 15, 2016 •

edited

kevin-brown Jun 15, 2016

kevin-brown Jun 15, 2016

tomchristie Jun 15, 2016 •

edited

foresmac Jul 1, 2016

tomchristie Jul 1, 2016

tomchristie commented Jul 4, 2016

marcgibbons commented Jul 4, 2016

tomchristie commented Jul 4, 2016

kevin-brown Jul 5, 2016

tomchristie Sep 22, 2016

rpkilby Sep 22, 2016

tomchristie Sep 22, 2016

swehba commented Nov 19, 2018


		def get(self, request, args, *kwargs):
		if request.accepted_renderer.format == 'corejson':


		router = DefaultRouter(schema_title='Server Monitoring API')

		The schema will be included in by the root URL, `/`, and presented to clients

Schemas & client libraries. #4179

Schemas & client libraries. #4179

Conversation

tomchristie commented Jun 8, 2016 • edited

Choose a reason for hiding this comment

tomchristie Jun 15, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomchristie Jun 15, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomchristie commented Jul 4, 2016

marcgibbons commented Jul 4, 2016

tomchristie commented Jul 4, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

swehba commented Nov 19, 2018

tomchristie commented Jun 8, 2016 •

edited

tomchristie Jun 15, 2016 •

edited

tomchristie Jun 15, 2016 •

edited