Document how to get 0.3 behaviour

[paultiplady]

I've just taken a stab at migrating from 0.3 to 2.0, and the experience has not been very smooth; to reproduce the old swagger-ui behaviour required a bunch of step-debugging through the new CoreAPI code to determine what was going on.

Worth adding some disclaimers to the migration docs?

• CoreAPI doesn't provide response schemas, which django-rest-swagger 0.3 did. This makes the generated docs less useful. (How to document the response body? #583)
• CoreAPI by default doesn't render endpoints which the logged in user doesn't have permissions for. To override this and get the original 0.3 behaviour of displaying all endpoints, you need to subclass the SchemaGenerator thusly:

from rest_framework.schemas import SchemaGenerator

class PublicSchemaGenerator(SchemaGenerator):
    def has_view_permissions(self, path, method, view):
        """
        Return `True` if the incoming request has the correct view permissions.
        """
        return True

[marcgibbons]

@paultiplady Thanks for the message. This project is no longer responsible for schema generation; this is now done by Django REST Framework.

Re: your two points.

CoreAPI doesn't provide response schemas.

This is true at the moment, and discussion is taking place here: encode/django-rest-framework#4502

CoreAPI by default doesn't render endpoints which the logged in user doesn't have permissions

This is true of the get_swagger_view shortcut as the request context is provided to the schema generator. To change this behaviour, write your own schema view and do not pass in the request.

See: http://www.django-rest-framework.org/api-guide/schemas/#using-an-explicit-schema-view

[paultiplady]

Hi @marcgibbons , thanks for the response. I'm aware of these points, as I spent a few hours digging into why this stuff wasn't working the same as in 0.3. I already commented on the issue that you linked; seems like it would be a good time for you to raise this library's requirements with Tom if you haven't elsewhere.

My suggestion was to document the differences so that users making the switch from 0.3 have a smoother migration path, and if they require response schemas, know that they are currently unsupported on the new version. Unfortunately I don't think that linking to the CoreAPI docs is sufficient; they are still a work in progress, and don't clearly describe how to get the 0.3 behaviour. Just saying "write your own schema" isn't very user-friendly when there are no examples of the sort of schema that we need in the CoreAPI docs; a simple example like the one I posted would have saved me a good chunk of time, and I would imagine that it would help others too.

[marcgibbons]

@paultiplady As described in the docs, 2.0 breaks from 0.3 versions, so there is no upgrade guide, so to speak. The schema generation and introspection is now performed by Django REST Framework and encoded into CoreAPI documents; so duplicating documentation from these projects doesn't really make sense. Likewise, feature requests and issues related to schema generation should be raised on those channels as these features could potentially benefit other documentation formats such as blueprint.

With that said, help is appreciated to improve documentation, perhaps an FAQ and expand on the example app.