[WIP] Add Open API schema generation. by carltongibson · Pull Request #6119 · encode/django-rest-framework (original) (raw)

Right, let's get this show on the road... (Putting up now for early feedback)

We're currently working towards moving to using OpenAPI as our default schema output. We'll also be revisiting our API documentation generation and client libraries.

We're doing some consolidation in order to make this happen. It's planned that 3.9 will drop the coreapi and coreschema libraries, and instead use apistar for the API documentation generation, schema generation, and API client libraries.
-- v3.8 release announcement — What's Next

Work targeting OpenAPI Specification Version 3.0.1 (Is that what we want?)

Overview

• Introduces OpenAPI versions of the schema generator and individual view inspector classes.
• Adds a DEFAULT_SCHEMA_GENERATOR_CLASS setting.
• Adds a generate_schema management command to output serialised schema to stdout. Closes Schema generation - management command #5839

To use this adjust your settings to use the OpenAPI generator/inspector classes:

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.inspectors.OpenAPIAutoSchema',
    'DEFAULT_SCHEMA_GENERATOR_CLASS': 'rest_framework.schemas.generators.OpenAPISchemaGenerator',
}

Any views where you've set an AutoSchema subclass will need adjusting.

Status: WIP

Management command has no subtlety at all (as yet).

Schema generation is stubbed to begin. We generate the paths and operations, but with no details (parameters, responses, etc). Nor do we have the other top-level keys that are available/required.

TODOs

• Refactor/Tidy new/existing code and tests.
• Management command
  • Options (?)
  • Tests
• Complete Open API schema (see below)
• Documentation.
• Deprecate CoreAPI schemas
• Deprecate internal docs, in favour of...
• Document migration to...
• Deprecate dynamic schema view (in favour of static) (?)

Help Wanted

I'm no expert on Open API. We need to fill in the top level keys and add the operation details. We need to make sure we're producing the correct output.

It's just a question of filling in the relevant parts of get_schema() and get_operation() but it's details.

All input here welcome!