Swagger-ui: Add support for Maps / additionalProperties
How to specify the swagger documentation annotation for generating model schema for Map attribute in a Java bean?
//groovy code
class Foo {
int id
String description
Map<String, Bar> targets
//few other attributes
}
For targets attribute, swaggerui shows 1 line but does not give the model schema for Bar class.
targets (Map[string,Bar])
How do I get Bar class Model schema as well in UI? Am using latest swagger library ('com.wordnik:swagger-jersey-jaxrs_2.10:1.3.8')
newtechfellas
All 47 comments
Swagger currently doesn't support maps, but the new version of it which is
really close is going to.
On Sep 3, 2014 10:49 PM, "newtechfellas" [email protected] wrote:
Reopened #558 https://github.com/wordnik/swagger-ui/issues/558.
—
Reply to this email directly or view it on GitHub
https://github.com/wordnik/swagger-ui/issues/558#event-160784249.
webron
on 3 Sep 2014
hmm thank you for the clarification. Any tentative date of new version with Map support?
newtechfellas
on 3 Sep 2014
About a week.
On 3 September 2014 23:57, newtechfellas [email protected] wrote:
hmm thank you for the clarification. Any tentative date of new version
with Map support?—
Reply to this email directly or view it on GitHub
https://github.com/wordnik/swagger-ui/issues/558#issuecomment-54365803.
webron
on 4 Sep 2014
Is this available now? If yes. any sample documentation on which swagger annotations to add for Map attribute?
newtechfellas
on 23 Sep 2014
This is more of a swagger-core issue, but you can try using 1.5.0-SNAPSHOT.
Keep in mind it's fresh so there may be bugs with it.
On 23 September 2014 18:48, newtechfellas [email protected] wrote:
Is this available now? If yes. any sample documentation on which swagger
annotations to add for Map attribute?—
Reply to this email directly or view it on GitHub
https://github.com/wordnik/swagger-ui/issues/558#issuecomment-56541431.
webron
on 23 Sep 2014
Yes, you can use the following annotations in an operation:
@ApiOperation(
value = "",
notes = "",
response = ResponseMessage.class,
responseContainer = "Map")
For a model:
will produce this:
{
"Person": {
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"firstName": {
"type": "string"
},
"address": {
"$ref": "Address"
},
"properties": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"birthDate": {
"type": "string",
"format": "date-time"
},
"float": {
"type": "number",
"format": "float"
},
"double": {
"type": "number",
"format": "double"
}
}
}
}
fehguy
on 23 Sep 2014
It did not work. I tried with latest com.wordnik:swagger-jersey-jaxrs_2.10:1.3.10 version. Swagger doc still shows targets (Map[string,Bar]) for attribute of type Map and no expansion for Bar class properties. (Referring to Foo class in my question)
Also tried the responseContainer attribute for @ApiOperation annotation. No difference with this either.
@ApiOperation(value = "get foo details for person id and foo id", response = Foo, responseContainer = "Map")
newtechfellas
on 24 Sep 2014
You need to be using 1.5.0-SNAPSHOT as the dependency.
fehguy
on 24 Sep 2014
the javadoc says 'Valid values are "List", "Array" and "Set"'.. support for Map is new?
lluu
on 24 Sep 2014
The javadocs are based on the 1.3.X release, not updated to 1.5.X yet.
webron
on 24 Sep 2014
where would I find 1.5.0-SNAPSHOT version? I checked http://repo1.maven.org/maven2/com/wordnik/ but did not find it.
newtechfellas
on 25 Sep 2014
I don't think the SNAPSHOT has been pushed yet. You can clone the repository and built it locally.
webron
on 25 Sep 2014
There is snapshot in sonatype. maven.org doesn't do snapshots, I believe.
Add this dependency to your pom.xml:
<repositories>
<repository>
<id>sonatype-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
Didn't mean to close it, will when it's supported in the UI
fehguy
on 26 Sep 2014
Any estimations when this will be implemented? Maps are ubiquitous in our api
mjgolinski
on 5 Dec 2014
@mjgolinski - are you using Swagger 2.0?
webron
on 5 Dec 2014
Yes
mjgolinski
on 5 Dec 2014
to be clear @mjgolinski maps are supported in the 1.5.0-SNAPSHOT version of swagger-jaxrs. In your response, just use containerType="Map". I think they're not complete in the UI, though.
fehguy
on 5 Dec 2014
@fehguy I need specifically swagger-ui support or at least estimates about when it will be implemented. Should I open a new ticket for it (I thought this one was about it)?
mjgolinski
on 7 Dec 2014
Hi - I also need it on the UI for submitting a map of strings... I checked out the ui and it doesn't seem to support it yet .. any timeline for this?
rosselet
on 9 Dec 2014
:+1:
DavidTPate
on 20 Feb 2015
:pray:
tsz662
on 12 Mar 2015
https://github.com/swagger-api/swagger-js/pull/262 should provide the basics for support here.
webron
on 4 May 2015
@whitlockjc this should be supported as of https://github.com/swagger-api/swagger-js/issues/230 but the petstore's /store/inventory doesn't show what I'd expect. The response definition looks like this:
{
"200": {
"description": "successful operation",
"schema": {
"type": "object",
"additionalProperties": {
"type": "integer",
"format": "int32"
}
}
}
}
but the model definition looks like this in the UI:
fehguy
on 8 May 2015
There is an existing issue for supporting additionalProperties that is/was awaiting feedback. I'm not sure why it's closed but here it is: https://github.com/swagger-api/swagger-js/issues/298
Supporting additional properties would not take a lot of effort but when I asked how it should be rendered, so we could do the work, no one answered and now the issue is closed.
whitlockjc
on 8 May 2015
I have the same problem.
Maybe we can find some representation ?
maver1ck
on 19 May 2015
@maver1ck I believe the method of displaying it is still pending. Although, perhaps @whitlockjc has a experimental branch with it? We're also trying to move the html representation of models into swagger-ui (where it belongs). Once the refactor is complete (ETA +/- week to get into develop_2.0, thereafter into master -> normal release cycle time) we can add the additionalProperties extra.
Hope this helps give you a timeframe :smiley:
ponelat
on 19 May 2015
Great.
Thank you for the answer.
maver1ck
on 19 May 2015
According to https://github.com/swagger-api/swagger-js/issues/298#issuecomment-100048445 this should be ready for implementation.
webron
on 28 May 2015
@whitlockjc I'm going in circles trying to track the state of these issues. You mentioned lack of feedback on this (https://github.com/swagger-api/swagger-js/issues/298) issue for the HTML rendering for additional properties. I personally think your suggestion was fine and there would at least be some thing there. I'd like to see that feature working. Does an issue need to be reopened or is it waiting on a future release? I can't tell from the way the issues link all around.
nikdunn
on 17 Jun 2015
I'm not the holdup and it's currently in the queue. /cc @ponelat
whitlockjc
on 17 Jun 2015
We can definitely re-stress this one. Right now we've just extracted some of the markup logic, and once that meets approval, we can add this on top of that. https://github.com/swagger-api/swagger-js/pull/486
ponelat
on 17 Jun 2015
Thanks for the feedback. So the additionalProperty issue was swept up into the separation of markup from swagger-js? That makes sense. I'll keep an eye on https://github.com/swagger-api/swagger-js/pull/486 and check it out once it hits the streets. Thanks guys!
nikdunn
on 17 Jun 2015
@nikdunn - it's one of the features that unfortunately didn't make the cut. I'm going to re-prioritize the issues on the projects soon, and this one is likely to get a bump.
webron
on 17 Jun 2015
Thanks, @webron. Do you have an idea when this might be available? If it's going to be a while, I could jump in and fix it with a pointer or two. Is there a release candidate branch?
@whitlockjc did you have an initial cut prior to the decision to defer to the separation of the markup from swagger-js? If you do, I might like to patch the current version if it's going to be a while before support hits a release.
nikdunn
on 17 Jun 2015
@nikdunn - the develop_2.0 branch is our development branch. Unfortunately, I can't give you a date for a point release. Once we accumulate 'enough' bug fixes and features, we'll release it.
webron
on 17 Jun 2015
@webron Can you point me to where in the code I would add support for additionalProperties on the development branch? Thanks.
nikdunn
on 17 Jun 2015
I wish I could :) That'd be more @ponelat / @whitlockjc / @mohsen1 / @fehguy's domain.
webron
on 17 Jun 2015
+1
dkirrane
on 7 Jul 2015
Is this in release 2.1.1 or not? I'm confused about the "Milestone v2.1.1" this issue is tagged with.
thjaeckle
on 29 Jul 2015
@thjaeckle - it is not. Our release process is not fully automated yet so there's a delay between releases and milestone updates. In general, the milestone is a target aspiration, it doesn't necessarily mean it's going to get in it.
webron
on 3 Aug 2015
Is Map[Long, List[CustomClass]] supported? For me in swagger.json I do not see the definition added for CustomClass. The Map is a property on only other classes. This is only class I am trying to use swagger for.
I am using jaxrs and the version of swagger-core is 1.5.3-M1
vakeeel
on 18 Nov 2015
Try to update to 1.5.4. Yes, maps are supported, but the key type is typically a string.
fehguy
on 19 Nov 2015
Hi,
we have a Java class Foo that contains a bars Map
bars: {
type: "object",
description: "...",
additionalProperties: {
$ref: "#/definitions/Bar"
}
},
The type Bar does not appear in the documentation. Any hints?
Thx
timmy82
on 24 Nov 2015
A part of my API returns a map in which the keys are arbitrary user defined strings.
"simple_statement_map": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/simple_statement"
}
}
This is not showing in the UI at all, much like @fehguy's example from May 8th. I'm using Swagger UI 2.1.4, which makes the combined fact that this is assigned to 2.1.3 and that it's been open for over a year a bit disconcerting.
JeroenDeDauw
on 30 Nov 2015
I feel like this is one of the primary things that is missing from our perspective. We love Swagger, but this issue with the Maps prevents us from properly documenting our API's.
cabbonizio
on 3 Dec 2015
Please track meta issue #1248. It will be handled there.
fehguy
on 7 Dec 2015
Related issues
andrecarlucci
·
3Comments
sgyang
·
4Comments
easyest
·
3Comments
songtianyi
·
3Comments
zilongl
·
3Comments
Most helpful comment
I feel like this is one of the primary things that is missing from our perspective. We love Swagger, but this issue with the Maps prevents us from properly documenting our API's.