Generate Pydoc on model properties.

[jkinkead]

Is your feature request related to a problem? Please describe.
I like well-documented APIs, and I can't figure out a way to get Pydoc (or even Python comments) attached to properties of a generated model class.

Describe the solution you'd like
OpenAPI objects in the schemas dict get turned into Python classes, with Pydoc matching the description field value.

I would like the properties of these objects to have the same behavior: If a entry in properties has a description, it should be attached to the attribute in the generated class as Pydoc.

Describe alternatives you've considered
Alternately, having simple Python comments on the generated class would be fine.

Additional context
Example truncated OpenAPI file:

{
  "components": {
    "schemas": {
      "SomeObject": {
        "type": "object",
        "required": ["my_prop"],
        "description": "This is my Object.",
        "properties": { "my_prop": { "type": "string", "description": "This is my property." } }
    }
  }
}

Desired output option 1:

class SomeObject:
    """This is my Object."""

    """This is my property."""
    my_prop: str

Desired output option 2:

class SomeObject:
    """This is my Object."""

    # This is my property.
    my_prop: str

[dbanty]

Hey @jkinkead thanks for the request! Better docstrings are definitely something I want to add in here, but I have never had good luck documenting attributes of classes with Sphinx. I prefer the Google-style docstrings which looks like it wants to document classes like this:

class SomeObject:
    """This is my Object.

    Attributes:
        my_prop (str): This is my property
    """

    my_prop: str

I feel like I've tried that in the past thought and neither my IDE nor Sphinx liked it. Does that style work for you? If not, does one of the ones you recommended play nice with Sphinx and/or some other docs generator? Eventually I'd like to provide an option in here to generate API docs into something nice & hostable on Read the Docs or similar.

[jkinkead]

Google-style would be just fine! From doing a bit of reading, it looks like the proper format for "attribute docstrings" (from PEP 257) is after the attribute; but it also sounds like these aren't available at runtime like other docstrings.

So, Google-style might be the move. :)

[dbanty]

This is actually done in 0.11.0 via #503 I think