Add support for Maps / additionalProperties

[newtechfellas]

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')

[webron]

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 #558.

—
Reply to this email directly or view it on GitHub
#558 (comment).

[newtechfellas]

hmm thank you for the clarification. Any tentative date of new version with Map support?

[webron]

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
#558 (comment).

[newtechfellas]

Is this available now? If yes. any sample documentation on which swagger annotations to add for Map attribute?

[webron]

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
#558 (comment).

[fehguy]

Yes, you can use the following annotations in an operation:

@ApiOperation(
  value = "",
  notes = "",
  response = ResponseMessage.class,
  responseContainer = "Map")

For a model:

https://github.com/wordnik/swagger-core/blob/develop_2.0/modules/swagger-core/src/test/scala/models/Person.java#L9

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"
      }
    }
  }
}

[newtechfellas]

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")

[fehguy]

You need to be using 1.5.0-SNAPSHOT as the dependency.

[lluu]

the javadoc says 'Valid values are "List", "Array" and "Set"'.. support for Map is new?

[webron]

The javadocs are based on the 1.3.X release, not updated to 1.5.X yet.

[newtechfellas]

where would I find 1.5.0-SNAPSHOT version? I checked http://repo1.maven.org/maven2/com/wordnik/ but did not find it.

[webron]

I don't think the SNAPSHOT has been pushed yet. You can clone the repository and built it locally.

[fehguy]

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>

[fehguy]

Didn't mean to close it, will when it's supported in the UI

[mjgolinski]

Any estimations when this will be implemented? Maps are ubiquitous in our api

[webron]

@mjgolinski - are you using Swagger 2.0?

[mjgolinski]

Yes

[fehguy]

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.

[mjgolinski]

@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)?

[rosselet]

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?

[DavidTPate]

👍

[tsz662]

🙏

[webron]

swagger-api/swagger-js#262 should provide the basics for support here.

[nikdunn]

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 swagger-api/swagger-js#486 and check it out once it hits the streets. Thanks guys!

[webron]

@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.

[nikdunn]

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.

[webron]

@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.

[nikdunn]

@webron Can you point me to where in the code I would add support for additionalProperties on the development branch? Thanks.

[webron]

I wish I could :) That'd be more @ponelat / @whitlockjc / @mohsen1 / @fehguy's domain.

[dkirrane]

+1

[thjaeckle]

Is this in release 2.1.1 or not? I'm confused about the "Milestone v2.1.1" this issue is tagged with.

[webron]

@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.

[vakeeel]

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

[fehguy]

Try to update to 1.5.4. Yes, maps are supported, but the key type is typically a string.

[timmy82]

Hi,
we have a Java class Foo that contains a bars Map<BarId,Bar>. The swagger.json is
bars: {
type: "object",
description: "...",
additionalProperties: {
$ref: "#/definitions/Bar"
}
},

The type Bar does not appear in the documentation. Any hints?

Thx

[JeroenDeDauw]

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.

[cabbonizio]

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.

[fehguy]

Please track meta issue #1248. It will be handled there.