Support non-json content types?

[cjllanwarne]

Hello and thanks for a great project!

I wondered whether there's any interest in support for non-json content types?

Two examples I have right now are that I'd like to annotate some existing methods to document:

• An API that returns no content. The only options I seem to have are None which comes back as null and an empty string, which comes back as "".
• A simple string value. I've refactored a method that used to be equivalent to return web.Response('foo') to be return APIResponse('foo') but over the wire, I'm changing the API behavior. It used to be returning foo but now it returns "foo".

This assumption that all API respond in json requirement seems to be coming from here?

Thank you!

[Dreamsorcerer]

* An API that returns no content. The only options I seem to have are `None` which comes back as `null` and an empty string, which comes back as `""`.

#21

* A simple string value. I've refactored a method that used to be equivalent to `return web.Response('foo')` to be `return APIResponse('foo')` but over the wire, I'm changing the API behavior. It used to be returning `foo` but now it returns `"foo"`.

I don't have any concrete plans for how non-JSON responses would work in the library just yet (and also not sure how these are represented in OpenAPI yet). First priority will be adding parameter and header support, before I can start thinking about this. But, feel free to provide suggestions on how the API should look for this.

[Dreamsorcerer]

So, merging thoughts from #40, maybe a valid approach would be to specify the media type in the decorator. When not using the default json type, it should not use/expect an APIResponse as the return type.

So, we might have something that looks like:

@SCHEMA.api(media_type="text/plain")
def handler(request) -> web.Response:
    ...

@SCHEMA.api()
def handler(request) -> APIResponse[str, Literal[200]]:
    ...

[cjllanwarne]

I like your suggestion. Are decorators powerful enough to see media_type="text/plain" and know to expect a different response type? Or would we need another decorator like @SCHEMA.text_api or whatever?

Pushing my own use case one more time, would something like @SCHEMA.api_doc(response_shape=...) where we don't validate the types but can use the information to build the openapi schema be possible?

[Dreamsorcerer]

That might be an option. Will come back to it once the higher priority stuff in done.