tfranzel / drf-spectacular

Sane and flexible OpenAPI 3 schema generation for Django REST framework.
https://drf-spectacular.readthedocs.io
BSD 3-Clause "New" or "Revised" License
2.38k stars 264 forks source link

Docstring from Django model not applied to scheme #755

Closed lexicalunit closed 2 years ago

lexicalunit commented 2 years ago

Describe the bug We have a class like:

class Employee(models.Model):
    """
    Salaried or contract worker.
    """
    ...

But after generating the schema.yaml file, we see the Employee scheme as:

    Employee:
      type: object
      description: |-
        Extended DRF ModelSerializer class which can avoid naming
        collisions and validate immutable fields

        Use a "_" suffix on field names to avoid conflicts, which will be
        automatically removed in the API field name

        Example:
            # To use an API field named "type" (which is a reserved Python builtin)
            type_ = CharField()

            class Meta:
                fields = ("type_",)
      properties:
        id:
          type: string
          readOnly: true
          pattern: ^[-a-zA-Z0-9_]+$

To Reproduce

python manage.py spectacular --file schema.yaml

Expected behavior Shouldn't the description here be generated from the docstring of the Employee class?

lexicalunit commented 2 years ago

Nevermind! The docstring needs to be in the EmployeeSerializer class, of course! 😅