Open API Code first, Polymorphic Map Values

Question

I want to generate Open API specs from Java code (code first). I am doing it by using following dependencies

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.15</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

I have JSON request like below

{
    "replacementVariables": {
        "salutation": "Ms",
        "firstName": "Jeff",
        "day": ["1", "2", "3" ],
        "points": ["24", "29", "13" ]
    }
}

The keys in the above example ("salutation", "firstName", "day", "points") are not fixed. Requester might send a new key say "lastName". Also values can be string or array. The backend logic has bee written to handle the different keys and values.

For deserialisation, I have used following object

private Map<String, Object> replacementVariables;

I am using jackson library for deserialisation

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.11.4</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.10.2</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.10.2</version>
</dependency>

The deserialisation happens perfectly into Map.

I need Open API doc generated for the above as follows

.
.
.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
.
.
.
components:
    schemas:
        Request:
          properties:
                replacementVariables:
                    $ref: '#/components/schemas/ReplacementVariables'
        ReplacementVariables:
            type: object
            additionalProperties:
                anyOf:
                    - string
                    - $ref: '#/components/schemas/ReplacementVariablesList'
        ReplacementVariablesList:
            type: array
            items:
              type: string

I am using @Schema annotation with anyOf, additionalProperties and additionalPropertiesSchema but it is not able to generate correct specs. I tried using @JsonTypeInfo and @JsonSubTypes. But I am unable to generate schema as above.

Please help in writing proper annotation that can generate correct Open API specs correctly.

score 0 · Answer 1 · answered Aug 07 '23 at 10:49

Reference: Swagger declaration schema = @Schema(implementation = Map.class) represents Schema as String in swagger-ui

Following configuration generated API specs correctly

@Schema(ref = "#/components/schemas/ReplacementVariables")
private Map<String, Object> replacementVariables;

@Configuration
@OpenAPIDefinition
public class OpenApiConfig {
    @Bean
    public OpenAPI replacementVariables() {
        Schema<?> replacementVariables = new MapSchema()
                .additionalProperties(
                    new ComposedSchema()
                        .addAnyOfItem(new StringSchema())
                        .addAnyOfItem(new ArraySchema().items(new StringSchema())));
        return new OpenAPI().components(new Components().addSchemas("ReplacementVariables", replacementVariables));
    }
}

Open API Code first, Polymorphic Map Values

1 Answers1