CODEWITHSUNDEEP
springopenapiswagger-editorspringdoc-openapi-ui
George
George

Reputation: 2512

OpenApi add example for request body

Am working with Spring boot and I am using springdoc-openapi-ui to generate spec files using swagger editor The issue Is, Am trying to avoid creating model classes just to use them in the request body to show them with swagger UI. For example :

    @RequestMapping(value = "/update/project/{id}", method = RequestMethod.POST,
    produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<String> projectUpdate(@RequestBody ObjectNode json, @PathVariable int id)  
    { ... }

If I use it like this, the example will be empty on the Swagger UI page. So as a solution, I have to do it like the following

public class CustomerCreateRequest {
    
    @JsonProperty
    private String ProjectId;
    @JsonProperty
    private String ProjectName;
    @JsonProperty
    private String ProjectDescription;
    @JsonProperty
    private String CustomerId;
    @JsonProperty
    private String CustomerName;
    @JsonProperty
    private String CustomerDescription;
    @JsonProperty
    private String BucketId;
    @JsonProperty
    private String API_KEY;
    @JsonProperty
    private String Name;
    @JsonProperty
    private String RedmineId;

And then I can use the model class I just created like the following.

@PostMapping(value = "/createUser")
    public ResponseEntity createCustomer(@RequestBody CustomerCreateRequest requestBody)
    { ... }

Question

Any Answer, Suggestion, Links are appreciated, the swagger docs was not helpful in my case.

Upvotes: 1

Views: 4029

Answers (1)

Gonzalo Mendoza
Gonzalo Mendoza

Reputation: 25

my two cents:

Is it ok to do a model class just for this purpose?

Yes, you should use a model class for your @RequestBody becouse every endpoint must have a contract to communicate the payload necessary to be consumed. It's a good practice add the annotations like

@Parameter(description="Some description", example="{\"foo\":\"bar\"}")
@RequestBody CustomerCreateRequest requestBody

Is there a way to add an example so the UI team will have an idea of how to use it.

No, Swagger will map a POJO class with decorators such as @Schema and others. ObjectNode has not a valid representation for the use case

I know that a model class can be helpful in generating a client for UI ( like JSClient ) But is it really necessary? I mean can't we overcome this issue?

Well, in my experience use tools as Swagger have more benefits than cons. It's necessary take care about the constraints related? I think so

Upvotes: 1

Related Questions