0

Context

Say you have:

public class Dto {
  private String name;
  private String List<String> customs;

  // getters and setters...
}

and

public class Custom {
  private String something;
  private String else;
  
  // getters and setters...
}

Your Spring MVC RestController receives a list of Dto:

@PostMapping
public String create(@RequestBody List<Dto> dtos) {
  return myService.process(features);
}

Input

However, you know that the client-side service which will send data to your controller will send something like this:

[
  {
    "name": "Bob",
    "customs": [
      "{\n        \"something\": \"yes\",\n        \"else\": \"no\"\n      }"
    ]
  }
]

Notice how the String is a json representation of the Custom class. Please assume this cannot be changed on the client-side and we have to deal with it on the server-side.

Question

Is there an OpenAPI annotation which would allow me to designate Custom as being the object to be automagically converted to a String which would then be used as the example in the UI?

By "used as the example", I'm talking about this automatically generated json (please disregard the actual data shown there since it doesn't match the presented simplified problem):

Swagger UI screenshot to better illustrate

I'm asking for an automatic set up because I would prefer not having to go back onto the String's specifics if we end up modifying the properties of the Custom class (removing the something attribute, for example).

We are using those Maven dependencies:

    <!-- Swagger / OpenAPI -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>3.0.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>3.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.4.1</version>
    </dependency>
2
  • How you are using springdoc and springfox together? Commented Sep 15, 2020 at 7:13
  • @SSK thanks for making me realize that! I removed springfox in my repo. Commented Sep 16, 2020 at 19:06

1 Answer 1

2

In order to designate DTO as being the object to be automatically converted to a string representation for the openAPI documentation UI, Swagger openApi provides a set of annotations found in this library:

<groupId>io.springfox</groupId>
<artifactId>swagger-annotations</artifactId>
<version>...</version>

You can make use of them to fix your problem, by using the @ApiModel annotation on your Dto.

By using these annotations all changes to your models are picked up and updated in the documentation automatically

Sign up to request clarification or add additional context in comments.

1 Comment

@ApiModel is from an older version of Swagger, but it is indeed what I was looking for, so I found the OpenAPI equivalent: @ArraySchema. Thanks!

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.