Include 'Models'

[normenmueller]

It would be advantageous if the Models section could also be included, via a switch, for example.

Within a respective YAML file, this is the definitions section.

[twskj]

Could you elaborate why does the information shown in the schema column is not sufficient?

[normenmueller]

To obtain a general overview of the definitions, that is, the data model.

For this, one would like --- so I think --- not to look at the individual paths, but only at the definitions independently.

[twskj]

I'll do some experiment and will get back to you. Thanks for your suggestion

[normenmueller]

@twskj Awesome! Thx!

[adoerler]

Hi,

thanks for creating pretty-swag 👍

I'm also missing the models section for the following reason:

In my case I've some enums defined in the properties like

efinitions:
  TestEntry:
    type: "object"
    required:
    - "testattribute"
      testattribute:
        type: "string"
        description: "Kind of testattribute used."
        enum:
          -  "abc"
          -  "def"
          -  "ghi"
          -  "jkl"
          -  "mno"

Although the data is included in the schema column, the possible Enum values are missing. Default values, example and format is missing too.

Please have a look at the swagger Petstore example used by http://editor.swagger.io/ It uses the following YAML: https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml

On http://editor.swagger.io/ it shows

After pretty-swag this information about the possible ENUMs, formats, examples and default values are missing:

Best regards Andreas

[Majstr]

I would also need enums to be displayed.

[twskj]

In this short term, We can use inline comment (description) to show enum, and default values if there aren't too many of them. For longer enum values, we can describe it in Summary section.

I'm still looking for an idea how to display example. I was thinking of maybe making it a tab or something that we can switch between schema and example but haven't got time to test it out.

And as always thanks for suggestions 👍

[Maaartinus]

@twskj what about just replacing the types by the example values? I mean just to toggle between

{
  "id": "integer",
  "email": "string",
}

and

{
  "id": 123,
  "email": "[email protected]",
}

This allows you can switch back and forth without loosing context.

[twskj]

I think I can swap example value in when there is an example value available.

My initial thought process is that if key naming is descriptive enough, we don't have to spell out for a developers. Or if needed we can use a comment to show such examples. But I can see that might be a little over generalized plus when having a lot of comment, they are not really align.