Strange Behavior of class docstrings

[chgad]

Hi,

i get to see a strange behavior when it comes to the display of a class docstring in the swagger UI.

The first Docstring where it occurs looks like this : """ This is a Filter Endpoint. It allows to filter it's Resource according to the databasefields an their values. Providing a field and it's value to filter by just use the common GET syntax.

This Means :
    * url\?\<first_fieldname\>\=value1\&\<second_fieldname\>\=value2

Resource:
    * MineralType

Fields available for this Resource are:
    trivial_name, systematics, variety, minerals,
    mohs_scale, density, streak, normal_color,
    fracture, cleavage, lustre, chemical_formula,
    other, resource_mindat, resource_mineralienatlas

Note to filter for systematics one needs this 'translations':
   * EL = Elements
   * SF = Sulfides & Sulfosalts
   * HG = Halogenides
   * OH = Oxides and Hydroxides
   * CN = Carbonates and Nitrates
   * BR = Borates
   * SL = Sulfates
   * PV = Phosphates, Arsenates & Vanadates
   * SG = Silicates & Germanates
   * OC = Organic Compounds

"""

When this Docstring gets converted only the last enumeration gets rendered, by markdown, with the normal "dots"

like this.

BUT: The first two do not get converted which looks quite strange. Am I doing anything wrong here ?

The next point is : The blank lines are ignored ?!

Thanks in advance.

[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.