Documentation for Non-Model Views/Viewsets

[thiagocharao]

I'm struggling with a similar scenario of this issue #3373. I have a very specific service layer that gives a pretty well formed return and my views/viewsets have one job, call this service and serialize its result.

The thing is, I have two serializers, one to validate query parameters and another one to serialize service's raw return. None of them are used as "required" by DRF as serializer_class resulting that their fields won't be considered by SchemeGenerator

I'm failing when trying to create custom documentation to each endpoint, since DRF is kind of model-oriented to generate its schemas (I could write down my own schema, but I would love if DRF generates it for me though), plus I'm using Swagger as interface.

In my opinion, it would be nice to permit create docstring to create coreapi.Documents by that it would be way more flexible. Any ideas how I could proceed for now?

[tomchristie]

We do need to do a better job of documenting the limitations of the automatic schema generation, and describing how to do things explicitly in the cases that it can't automatically handle, yup.

[thiagocharao]

Fair enough, for now I will write schemas explicitly then.

[tomchristie]

That's perfectly sensible, yup. Either:

• Internally as CoreAPI representations.
• Externally as schema files that you then load into CoreAPI and expose in whatever format you want.
• Externally as schema files that you expose statically.

[thiagocharao]

Yeah, internal CoreAPI representations are my best choice now, as I see, I think this kind of docs should be generated (as it is in a well defined standard, by serializers, fields, routers...) or something like docstrings definitions (YAML, JSON...) but really close to the endpoint code and then schema would be generated from there. django-rest-swagger used to do this kind of thing taking advantage of YAML docstrings, but it is deprecated since version 2.0.

[carltongibson]

This should be handled with the changes coming in with v3.7.

Override AutoSchema (or provide a ManualSchema) for your endpoint and use whatever means necessary to generated your schema. ("Specify by hand" is viable.)

The new system allows doing this per-view, so you don't loose auto-generation elsewhere.

I'm going to close this for now. Happy to new issues on specifics once you've played with the new system!

[juja256]

@carltongibson What about AutoSchema and ManualSchema for ViewSet? Will it appear in future releases? Or maybe I should split ViewSet into Views and provide ManualSchema for each of them?

[carltongibson]

Viewsets are APIView subclasses. (It already works.)