Document Hashmap with @Schema

[matus-m]

hi,

how would one describe an api response, that returns Map<String, List<ComplexObject>> using the v2 annotations? Or Map<String, ComplexObject>?

According to OA3 schema it is possible to model like this, using additionalProperties:

openapi: "3.0.0"
info:
  title: Swagger Petstore
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /petGroups:
    get:
      operationId: listPetGroups
      tags:
        - pets
      responses:
        '200':
          description: Pets grouped by Ownername
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/MapResponse"

 
components:
  schemas:
    MapResponse:        # <---- dictionary<String,Array<Pet>>
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Pets'
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
   

But I do not see a way, how to describe this structure on the server side using java annotations, as @Schema does not have additionalProperties.

(end goal is to generate schema from server code, or at least to validate, that the server code matches the schema above)
Thanks

[frantuma]

one way to achieve what you want is having your resource method return e.g. Map<String, List<Pet>> which would result in a spec with a response to the one above:

        @GET
        @Path("/path")
        public Map<String, List<Pet>> simpleGet(String data) {
            return null;
        }

a more "invasive" alternative would be defining a class extending e.g. HashMap<String, Pet> to be used in implementation field of @Content annotation within @Response:

class MyModel extends HashMap<String, Pet> {}

@Operation(responses = {
  @ApiResponse(
    responseCode = "200",
    content = @Content(
      mediaType = "application/json", 
      schema = @Schema(implementation = MyModel.class)))
  }
)
@GET
@Path("/path")
public Whatever simpleGet(String data) {
      return null;
}

[clounie]

It seems like something that should be automatically introspected and applied, especially for Map<String, XXX> - no need for extra syntax.

[ndtreviv]

Something like this would be great:

content = @Content(map = @MapSchema(key = @Schema(implementation = String.class), value = @Schema(implementation = XXX.class)))

And so would produce the following in swagger ui:

{
  "key": XXX > { ... }
}

[mchmielarz]

Hi! @frantuma How's the progress with this one?

[haarisdev]

Hello @frantuma, is there any update on this? It seems bizarre that describing an API response using a map isn't natively supported the same way that Schema or ArraySchema are. The current solutions that you've shown above lead to bad practices

[MansSandberg]

Any update on this? @frantuma
I encountered this problem this week when I implemented an API that returns a HashMap.

[atulkumarr123]

I also faced this limitation today, Does anyone know the status on this?

[Plonk42]

Hey @frantuma , any update on this one? Thanks!

[amccourt]

Also looking for an update on this @frantuma

[frantuma]

#4475 adds support for additionalPropertiesArraySchema in @Content annotation which should cover all use cases mentioned in this ticket related to additionalProperties. This test and related resource class demonstrates usage in various scenarios.

Closing ticket, will monitor for any comment/feedback

[nahmias22]

Is there somewhere an example on how a map should be described based on the new changes?

[alexlitovsky]

#4475 adds support for additionalPropertiesArraySchema in @Content annotation which should cover all use cases mentioned in this ticket related to additionalProperties. This test and related resource class demonstrates usage in various scenarios.

Closing ticket, will monitor for any comment/feedback

I am still not seeing how this can be used to document a Map (key type, value type) using the provided examples. It should be much more obvious.