At the bottom of the Swagger UI display is a Models section. (For example,
see http://petstore.swagger.io/ and scroll to the bottom.) I don't
understand the purpose of this Models section. The Model information is
already in the parameters or responses sections. Why do we need this
repeated at the end?
I realize that I can easily hide this section with a style:
section.models {
1. display: none;
}
However, I feel like the purpose of this section isn't explained anywhere.
Can you provide some more details?
Also, when I'm describing a schemas object, suppose I have an object that
contains and object that contains an object. I could build out the
describing in the same schemas object, but I could also point each
sub-object to a new schema object. If so, then Swagger UI will show each
object on its own.
For example, here's a schemas object that contains a number of sub-objects:
components:
schemas:
WeatherdataResponse:
title: weatherdata response
type: object
properties:
query:
type: object
properties:
count:
type: integer
description: The number of items (rows) returned --
specifically, the number of sub-elements in the results property
format: int32
example: 1
created:
type: string
description: The date and time the response was created
example: 6/14/2017 2:30:14 PM
lang:
type: string
description: The locale for the response
example: en-US
results:
type: object
properties:
channel:
type: object
properties:
...
The Models section will then show this as a single object with a lot of
collapse/expand sections for the sub-objects.
I could also approach the schemas description like this:
components:
schemas:
WeatherdataResponse:
title: weatherdata response
type: object
properties:
query:
$ref: '#/components/schemas/Query'
Query:
title: query
type: object
properties:
count:
type: integer
description: The number of items (rows) returned -- specifically,
the number of sub-elements in the results property
format: int32
example: 1
created:
type: string
description: The date and time the response was created
example: 6/14/2017 2:30:14 PM
lang:
type: string
description: The locale for the response
example: en-US
results:
$ref: '#/components/schemas/Results'
Results:
title: results
type: object
properties:
channel:
$ref: '#/components/schemas/Channel'
Channel:
title: channel
type: object
properties:
units:
description: Units for various aspects of the forecast. Note that
the default is to use metric formats for the units (Celsius, kilometers,
millibars, kilometers per hour).
$ref: '#/components/schemas/Units'
...
The Models section will then show various objects on their own.
Looking at the Swagger Petstore example, it seems like the latter is more
followed, but it's hard to tell. Which approach better aligns with best
practices for OpenAPI spec descriptions?
Note that this follow-up question relates to my first question. Since I
don't fully understand the purpose of the Model, I can't decide whether a
user would want to see the entire schemas object with all levels of nesting
included directly, or whether it's better to break it out into separate
objects.
Thanks,
Tom
--
You received this message because you are subscribed to the Google Groups
"Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/d/optout.
