Microprofile4/OpenApi3, how to define example request value?

Question

In my setup I am developing a Microprofile4 (Quarkus2) Java application. This comes with OpenApi3.

In this application, I want to define an example for a POST request parameter.

import org.eclipse.microprofile.openapi.annotations.media.Content;
import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;

...    

// IntegerInterval is a simple data class, 
// having to int properties "start" and "end".
public List<IntegerInterval> returnIntervals(
  @RequestBody(description = "Test description", 
    content = {@Content(example = "[{\"start\":0,\"end\":1}")}) 
  List<IntegerInterval> intervals) {

  return intervals;
}

While the "Test description" shows up in the OpenApi specification, the example value does not:

/merge-intervals
post:
  requestBody:
    description: Test description
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/IntegerInterval'
  responses:
    "200":
      ...

score 0 · Accepted Answer · answered Jul 08 '21 at 12:41

You have to add a mediaType to the Content.

public List<IntegerInterval> returnIntervals(
  @RequestBody(description = "Test description", 
    mediaType = javax.ws.rs.core.MediaType.APPLICATION_JSON,
    content = {@Content(example = "[{\"start\":0,\"end\":1}]")}) 
  List<IntegerInterval> intervals) {

OpenAPI spec:

/merge-intervals
post:
requestBody:
  description: Test description
  content:
    application/json:
      schema:
        type: array
        items:
          $ref: '#/components/schemas/IntegerInterval'
      example:
      - start: 0
        end: 1

Microprofile4/OpenApi3, how to define example request value?

1 Answers1