Support defining "additionalProperties" in @Schema annotation

[knutwannheden]

With #360 support was added for properties, but I can't find any support for additonalProperties (see https://swagger.io/docs/specification/data-models/dictionaries/). AFAICT it looks like the model does support additional properties (see also #100), but I cannot find anything in the @Schema annotation.

[EricWittmann]

We talked about this a little bit on the spec hangout call today. Clearly the @Schema annotation is missing the additionalProperties property. That said, the OpenAPI spec allows additionalProperties to be either a boolean or another @Schema.

My question for @knutwannheden is this: what is your particular use-case? A boolean property would be easy enough to add. But if you're using the object variant of the additionalProperties property, that's a little tricker.

Can you give us an example of what you're doing?

[knutwannheden]

My background is that we have a large set of JavaEE services annotated using swagger-core 1.5 annotations which we are now migrating to MicroProfile OpenAPI. In the existing code we have many cases where we are using @ApiOperation(..., responseContainer = "Map") or @ApiResponse(..., responseContainer = "Map"). The Java method's return type is in fact typically Response, but the payload is Map<String, ...>.

I was now reading the specs trying to figure out how to best map this to MicroProfile OpenAPI annotations and AFAICT https://swagger.io/docs/specification/data-models/dictionaries/ suggests that the additionalProperties should be used.

[EricWittmann]

So in that case you are definitely looking for the more complex variant of additionalProperties where it is a schema, not a boolean. Thanks for the feedback.

One thing you could consider doing is defining a re-usable named Response (either by including it in a static openapi.yaml file in your deployment or by using a custom ModelReader class). Then you can simply use @ApiResponse(ref="#/components/responses/NamedResponse") everywhere it's needed.

https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java#L131

There are probably other approaches you could take too. Thoughts on other options, @MikeEdgar ?

[MikeEdgar]

One other option might be to define a dummy class that contains the type information, then use that as the @Schema#implementation class in your @APIResponse.

static class YourTypeMap extends java.util.HashMap<String, YourType> {};

Then:

@APIResponse(
  responseCode = "200",
  content = @Content(
    mediaType = "application/json", 
    schema = @Schema(implementation = YourTypeMap.class)))

[flo-ryan]

@MikeEdgar I'm facing the same issue (having used responseContainer = "Map" so far) and hence tried your suggestion, however for me the result in the generated openapi.json always looks like this:

"MyTypeMap" : {
  "type" : "object"
},

This seems to be the output, regardless of the map's key/value types, e.g.:

• Map<String, Long>
• Map<String, MyType>
• Map<MyType, String>
• Map<MyType, Map<String, Long>>

Am I missing something here?

[MikeEdgar]

@flo-ryan , you're right - I was just spit balling that answer and it turns out not to work (at least in SmallRye). You might try to put a dummy @Path that returns the Map type you require, then use the OASFilter to re-work the output. Obviously this is a hack.

Longer term for the next release (2.1?), perhaps @Schema could be extended with these?

• Class<?> additionalProperties() default Void.class;
• boolean additionalPropertiesAllowed() default false;

Any thoughts on this, @EricWittmann, @phillip-kruger, @msmiths ?

[effywu]

Hi guys, we are also in need to have the support of additionalProperties: true in the Schema annotation. Do we have any plan recently for adding this? Thank you.

[MikeEdgar]

@effywu - I think once version 2.0 is released we will be able to take a more serious look at things like this.

[rbertoncelj]

Hi, any news on this?

[MikeEdgar]

Candidate solution for 3.1:

Add to @Schema:

• Class<?> additionalProperties() default Void.class;
• boolean additionalPropertiesAllowed() default false;