Schema generation doesn't support response schemas

[gcbirzan]

This is a useful feature, at least for swagger, and the way things are right now it cannot be implemented from outside of DRF, since the Link object doesn't contain the schema for the response.

While the fields can be implied from the input fields, for read only endpoints this is not an option.

[tomchristie]

Correct. That's a design decision within Core API, because it comes across to me as unnecessary.

1. Generic clients do not need to have a strictly specified response structure in order to function.
2. Specifying response structures is an unbounded domain. Better just to describing expected responses in documentation (eg in the link description.)
3. Responses might in any case actually end up coming from one of many possible intermediaries. No way of knowing for sure what possible range of error responses might actually occur.

Perhaps this'll change someday, but for now I don't see sufficient clear value, given the complexity it adds.

[rygwdn]

We actually find the response schema to be very useful with swagger/openapi. It gives us:

• Consistent response body documentation in the automatically generated docs
• Documentation which is testably accurate (e.g. via a generic OpenAPI validating middleware)
• Field-level documentation by providing access to the serializer help_text in the schema
• The ability to generate response body objects in statically typed languages (Java, etc.)

We deal with the complexities you mentioned by:

• Using a generic type when the response can vary (e.g. a generic json "Object" response body with details in the description)
• Using OpenAPI "formats" to further specify anything that's not a plain "string" or "int", etc. The formats can be anything, so we can introduce new "types" easily
• Support for overriding the schema at various layers - the ViewSet can specify a different schema than what the tool thinks it would have, and we have hooks that do transformations on the schema to support our own extensions (e.g. to add tags, show/hide apis based on environment, modify descriptions, add pagination data, etc.)

[tomchristie]

Indeed. I've been warming to introducing some of this. I'll reopen this against 3.5 in order to keep track of what does and what doesn't go it. It's possible that we might end up part-way towards this (eg. example responses, but not full response schemas) or that we might completely defer it until later, but either way I think coreapi does need to be able to express this enough to be useful for docs generators.

[tomchristie]

Alrighty, there's plenty in 3.5 that improves the schema handling.
We'll be looking at API documentation as part of the 3.6 headline features,
which will likely include having extra information in coreapi in order to support the docs generators.

Most likely we'll initially be looking at response examples, rather than response schemas, but it's possible that we'll end up with both.

[wtfuii]

@tomchristie I'd prefer schemas, as i.e. https://generator.swagger.io/ generates full featured client libraries out of swagger files, which could be generated out of coreAPI data.

If the response schema is missing, the generated library does not specify the model. which makes this whole code generation pretty useless for static typed languages such as TypeScript, Java or C#.

[tomchristie]

@wtfuii: Not necessarily - get the pattern right and you can perfectly well create a dynamic client library within statically typed language. (For a parallel to this see, eg. browser implementations) We may or we may not follow swagger's choice here - remains to be seen.

[thomasf]

I might be missing something since I just started looking for a solution to this but It seems like it would be great if there was some kind of "generic" class for non model views with an optional get_response_serializer or something. I guess the main downside is that it wouldn't automatically translate to usage with @detail_route() but other than that it seems to me that it could be a solution which is similar to what already exists.