Hi Tom,
The display of the models at the bottom of Swagger-UI is a result of the merge between the previous versions of Swagger-UI and Swagger-Editor. Swagger-Editor had a models view, and we’ve got numerous requests to have a similar view in Swagger-UI – this is the result. Not surprising, we’re not getting opposite requests and we might add a configuration option to remove its rendering. For the Editor though, it makes sense to have it as a live rendering of what you design. As for inlining definition vs referencing then – I tend to recommend using references. That allows for reusability, if needed, it’s easier to name the models, and it makes generated code cleaner. From: <[email protected]> on behalf of "[email protected]" <[email protected]> Reply-To: "[email protected]" <[email protected]> Date: Monday, October 30, 2017 at 13:11 To: Swagger <[email protected]> Subject: what's the purpose of the Models section in Swagger UI? 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. 2. 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. -- 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.
