Strange Behavior of class docstrings

[axnsan12]

Strange Behavior of class docstrings

[axnsan12]

Hello,

Class docstrings are handled completely by the Django Rest Framework docstring extraction mechanism. I don't know exactly how that works, but I'd assume the docstring is just taken as-is -- you could look into the json response returned by /swagger?format=openapi to see exactly what is output.

This then lands into the Swagger Operation#description field, which is rendered as GFM (GitHub Flavored Markdown).

TL; DR: make it valid markdown

[chgad]

I found the following:

drf-yasg - Yet Another Swagger Generator

drf-yasg is a Swagger generation tool implemented without using the schema generation provided by >Django Rest Framework.

It aims to implement as much of the OpenAPI specification as possible - nested schemas, named >models, response bodies, enum/pattern/min/max validators, form parameters, etc. - and to generate >documents usable with code generation tools like swagger-codegen.

This also translates into a very useful interactive documentation viewer in the form of swagger-ui:

from DRF which seems quite strange, as u said the putput is created

by the Django Rest Framework docstring extraction mechanism.

[axnsan12]

I don't see how that relates to what I said. Your first quote is taken from the "third party libraries" section of Django rest framework documentation. The mechanism I am talking about (and linked to) is described in the documentation section for schema generation

[chgad]

Well sorry for just quoting it and not leaving a word there, i thought it was clear what i was referencing there.
I understand the quoted passage as follows: Yasg-swagger produces Documentation of DRF-Endpoints but without utilizing the DRF mechanism of schemageneration in which the extraction of Docstrings is included.

Is this a wrong understanding?

[axnsan12]

Oh, I see now. Well, the docstring parser is reused from DRF, as documented. The other parts (SchemaGenerator, AutoSchema, ManualSchema, etc) are not used.

[chgad]

Oh, so this was my fault in missunderstanding. Btw. I solved my Problems with the Markdown.

For Users reading this in the future:

1. Allways use a "space"-character before a : as long as the word/s before it is not a method name of your API endpoint(related to the docstring extraction mechanism). If you continue with out a blank the extraction mechanism tries to look for a method call like the word/s before the : ; and if it fails will cut the string straight off.
2. Never indent the first level of any enumeration (if ordered or not). Markdown will look for a "real" first level and if it does not find any, it will just put a * where a

belongs.
3. Allways end an enumeration with an empty line.