what's the purpose of the Models section in Swagger UI?

[tom...@gmail.com]

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

[Ron Ratovsky]

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: <swagger-sw...@googlegroups.com> on behalf of "tom...@gmail.com" <tom...@gmail.com>
Reply-To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Date: Monday, October 30, 2017 at 13:11
To: Swagger <swagger-sw...@googlegroups.com>
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;

}

--
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 swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[tom...@gmail.com]

Thanks for the explanation. I agree that breaking up the references in components makes more sense to allow for re-use. It's also easier to code because one small error won't make the whole model fail. However, the Models view itself, where each object stands alone, still doesn't make much sense to me. I would prefer an option in the Swagger UI parameters to hide this display. The CSS works fine but it feels like I'm cheating to hide something that should normally be shown (for reasons that aren't clear).

Should I file a feature request in the Swagger UI Issues tab for this parameter to be added in the future?

[Ron Ratovsky]

The feature request already exists - https://github.com/swagger-api/swagger-ui/issues/2834

--