Swagger-ui: Render models in UI code, not JS

[fehguy]

This may be a duplicate, but we need to move the rendering of models out of swagger-js and into swagger-ui.

[fehguy]

• [ ] add rendering of read-only attributes
• [ ] update rendering in responses to show complete schemas for each response code. See https://github.com/swagger-api/swagger-ui/issues/671, https://github.com/swagger-api/swagger-ui/issues/640, https://github.com/swagger-api/swagger-ui/issues/1248, https://github.com/swagger-api/swagger-ui/issues/1055
• [ ] add formats in rendering, https://github.com/swagger-api/swagger-ui/issues/1202
• [ ] render examples in UI, not JS, https://github.com/swagger-api/swagger-ui/issues/1213
• [x] XML examples #583, #744
• [ ] Add map rendering #558
• [ ] Consider different JSON renderer, #863

[webron]

Shouldn't there be an equivalent issue in swagger-js for removing it?

[makimat]

Sorry but being new here, could someone tell how can I find out which release version has or will have this issue fixed?

[webron]

@makimat - we haven't set a plan for it yet.

[yonderblue]

:+1: It appears the issue I mentioned over at https://github.com/swagger-api/swagger-spec/issues/303 is caused by this
Basically when I try to use a mimetype for the produces like multipart/mixed, I can't get the example to show unless I use object, and then it shows in an undesirable way. String is the type that would work as a workaround, but it doesn't show.

[yonderblue]

Also a big :+1: to getting readOnly to have meaning in the UI.

[sschwell]

+1 for showing model descriptions in the UI

[jscti]

+1

[alexkrishnan]

We would also really love to have support for the readOnly property!

[treidco]

+1 for this feature!

[matoushavlena]

+1

[JeroenDeDauw]

:+1:

[luigibianchi]

+1

[cabbonizio]

Hi, is there an update to when we will be able to document Maps for JSON responses? I'm trying to push Swagger in our organization and this is one of the things I have trouble explaining to the masses that we cannot show JSON schemas with maps.

[fehguy]

Simple maps are easy but complex maps (values which are complex models) are tricky. The most helpful input would be how you'd expect them to appear in both the sample and schema views

[cabbonizio]

@fehguy fair enough! I'll be in the office soon and will push some examples over to you. Stay tuned and thanks for your response.

[cabbonizio]

Here's what I propose @fehguy:

Here is the sample JSON. This a simple response of a map of product objects with the key being the product number.

{
    "products": {
        "01234": {
            "shortDescription": "Sample Product Description",
            "price": 100.00
        },
        "56789": {
            "shortDescription": "Another Sample Product Description",
            "price": 50.00
        }
    }
}

Here is how I propose (roughly!) it should look in the model schema view:

Here is how I propose (in YAML using Swagger editor) we define a map:

    Response:
      description: "Sample description"
      type: object
      properties:
        products:
          type: map
          key:
            description: "Product identifier"
            type: string
          value:
            $ref: "#/definitions/Product"
    Product:
      description: Product Object
      type: object
      properties:
        shortDescription:
          description: Sample description.
          type: string
        price:
          description: Price of product.
          type: number          

[cabbonizio]

I hope this helps @fehguy. I had a few developers at my desk to put this proposal together for maps as many of us in the organization are taking advantage of maps within our response models and we're all big fans of Swagger. As I said before this is one of the main missing pieces to complete our documentation. There are others questioning the use of Swagger due to this limitation and I'm trying to evangelize it. I hope the example above helps provide a general guideline what we're looking for and I know other users of the Swagger community have been asking for this. Thanks very much for your attention to this and hope there's something cool that comes out of this!

[fehguy]

thanks @cabbonizio this is a pretty easy fix in the short term. There are some limitations, though, that make it harder to support, such as in-line map definitions, etc.

[cabbonizio]

@fehguy, thanks for the response I'm excited to hear this would be an easy fix. Just curious, is this a "fix" or actually an "enhancement" since maps are currently not supported? Either way, I'm hoping maps will be available soon.

I agree, complex map definitions and in-line definitions would be challenging, but like anything else those can be incremental and if you show people Swagger can support maps, even if functionality is limited at the start, this is a step in the right direction.

Curious, how soon would I be able to test something out for map support?

[fehguy]

@cabbonizio we are moving the code into swagger-ui right now. Then the rendering will be much easier to do.

[webron]

@cabbonizio - Swagger (or rather JSON Schema) supports map definitions in a different way, which potentially adds to the complexity of the implementation. There's no type: map.

Maps are controlled via the additionalProperties property. JSON doesn't support non-string properties, so the key will _always_ be a string. The value is defined by whatever is defined under that property. Following the example you provided, it would be:

    Response:
      description: "Sample description"
      type: object
      properties:
        products:
          type: object
          additionalProperties:
            $ref: "#/definitions/Product"

Hope this clarifies it.

[cabbonizio]

I thought I tried this before but will give it another whirl. If it at least renders the definition then i can kust describe it's a map and our api clients will hopefully get it

[webron]

Well, it won't. The display of maps is not yet supported in the UI as @fehguy mentioned. That's why he asked for suggestions on the display.

[cabbonizio]

Do you recommend an issue be opened (map support) on the OpenAPI GitHub for tracking? You mentioned any asks for changes to the spec be opened there. On here i suppose we should just keep this open for the UI and rendering possibilities. Sound like a plan?

[webron]

There is map support in the spec (additionalProperties), so there's no need for a ticket about it. This is a tooling issue, not a spec.

[cabbonizio]

Ah, so additionalProperties IS used for map support which covers spec perspective, all about the tooling...got it.

[webron]

Yup, sorry of my previous explanation was confusing.

[cabbonizio]

@webron you are very helpful no worries. Who can complain you are responding over the weekend? Very much appreciated!

[webron]

Thanks for the feedback, have a great weekend ;)

[cabbonizio]

@fehguy @webron curious any further discussions/ideas on when Swagger UI can render the additionalProperties (for maps)? I was curious if my suggestions on display earlier in this issue on added any value. Thanks!

[gullerya]

Hi all,
I do see some work is going on about to show the XML schema in body preview, so just to be sure: is it already available feature, soon to be available, ETA?
I'm struggling with my configuration to get XML shown, but it's always JSON that is previewed.

[webron]

@gullerya XML is currently rendered in the UI

[gullerya]

well, i must be doing something wrong then:
AFAIU, all i need to do is to set "consumes": ["application/xml"] on the POST/PUT operation, am i missing something?
Should this be asked in another thread/forum or is it okay here?

[webron]

@gullerya may be better to open a new ticket so we can cover it there easily. If you can, please provide the spec itself or something close that reproduces the issue.

[koekemos]

Hi all,

Has the issue been resolved to display XML in the model and model schema on the swagger UI ?
Links #583, #744

[fehguy]

Try master

[kjschnei001]

@fehguy @webron Is there any update on the work to display maps in the swagger ui?

[fehguy]

Yes, we are doing substantial work in the rendering code now.

[kjschnei001]

@fehguy That's great news! Our team is looking to utilize this functionality as soon as it is available.

[cabbonizio]

Looking very forward to seeing map support in the UI!

[Espolette]

Hi all,
@fehguy @webron Have you a date for the support of maps in Swagger UI ? We are also very interested in this development.

[webron]

No ETA I'm afraid. We're working on something that will greatly impact this feature request, but I can't say when it'll be available.

[Espolette]

Ok thanks.

[bbrazsilveira]

Tracking map support. Thanks

[angela-mylo]

It's been six months since the last comment. Any update on the schema support for maps?

[KaranKamath]

Any ETA / priority assigned to this? Our organization loves swagger, but this is a deal breaker. Don't mind an experimental branch with _any_ json rendering for additionalProperties supported.
@fehguy

[webron]

@KaranKamath we should have an experimental version within a few weeks.

[DavidMhn]

Is there any update on map support?

[mrapavy]

+1

[fehguy]

This has been 100% implemented in our soon-to-be released update to the UI.

[cabbonizio]

Woo hoo! Excited to see what's in store.

[webron]

So are we ;)

[matthiasBender]

@KaranKamath, @fehguy: Is there a branch where we may see this experimental feature? We would really like to try it out. Or is there a plan on when we may expect this feature to be released?

[webron]

It will be available for testing in a few weeks.

[xiaochengxuyuan]

so cool

[webron]

Done in 3.0.