WIP: Content type specification

[mbierma]

This is a quick and dirty proof of concept to allow for the specification of content type other than application/json for OpenAPI 3 generation. Currently, it is possible to create an endpoint without specifying the response_body_schema, and then returning a Response object with the desired content type:

@registry.handles(
    rule='/todos',
    method='GET',
    query_string_schema=GetTodosQueryStringSchema(),
)
def get_todos():
    return send_file(pdf, as_attachment=True, mimetype='application/pdf')

However, in existing implementation, the generated swagger specification does not reflect the correct content type. This PR is intended to demonstrate a way to allow for the specification of content type using a __content_type__ magic attribute. Additionally, a primitive response_body_schema type is used to allow for responses that are not json objects.

class PDF(m.fields.String):
    __content_type__ = "application/pdf"

@registry.handles(
    rule='/todos',
    method='GET',
    query_string_schema=GetTodosQueryStringSchema(),
    response_body_schema=PDF
)
def get_todos():
    return send_file(pdf, as_attachment=True, mimetype='application/pdf')

Possibly related to #91

[badam5]

Hey @mbierma! Thanks for the PR. Is this still WIP or would you like preliminary feedback?

[mbierma]

Mostly just looking for preliminary feedback. The main intent of this PR is to:

• Generate the correct OpenAPI 3 specification when the content type is not application/json
  • Account for the case where a single endpoint may return different content types based on the return code. For example, there may be consistent application/json error responses across all endpoints, even for ones that return a csv/file/etc.

Since this deals with response content types, and #91 is dealing with content negotiation, it would be great if there was a consistent interface between the code here and what you're planning for the future

[badam5]

@RookieRick @airstandley Tagging you folks here, since you may have more context than I do regarding content types! Any thoughts?

[airstandley]

@mbierma The example you've given uses a Field rather than a Schema which presents all kinds of issues. I'm assuming that's a small mistake and you intended for PDF to be a marshmallow.Schema or some class that implements the dump interface. I'd be very interested if you could provide an example that actually handled validation (some assertion that pdf data is being returned).

The approach you are taking has some merit, but I think it would be helpful if you included a working example of a simple handler which returned a valid pdf(or something easier like plain text) when hooked up to a test app.

I also think we want to keep in mind that at least in OpenApi v3 you can specify multiple content-types. I'd image this behaviour would be much more useful it we could introduce a way to support multiple content-types (eg. a handler that can return video/mp4 or video/avi)

[mbierma]

@airstandley thanks for the feedback. I'm going to be working on a better example

I am definitely in agreement that it would be much more useful to introduce a way to support multiple content-types. Do you have any recommendations on how to specify something like that? The first things that come to mind are

@registry.handles(rule="/foo/media", method="GET",
                  response_body_schema={200: [MP4(), OGG(), Quicktime()]})

or

@registry.handles(rule="/foo/media", method="GET",
                  response_body_schema={200: {'video/mp4': MP4(),
                                              'video/ogg': OGG(),
                                              'video/quicktime': Quicktime()}})

For the first case, there'd likely be some validation that each response schema in the list contains a unique __content_type__ magic attribute. For the second example, the magic attribute could be done away with, since the content-type is specified in the keys.

[airstandley]

I haven't checked the 2.0 spec, but 3.0 specs content as a map so I'd say that

@registry.handles(rule="/foo/media", method="GET",
                  response_body_schema={200: {'video/mp4': MP4(),
                                              'video/ogg': OGG(),
                                              'video/quicktime': Quicktime()}})

seems like a great approach and then we can fallback on the old behaviour and assume 'application/json' if just a schema is given.
@RookieRick What are your thoughts on this?

[gtmanfred]

Those defaults sound good to me. Is there any chance that you still plan on doing this work @mbierma ?

Thanks,
Daniel