CODEWITHSUNDEEP
javaswaggeropenapiquarkus
Luisao
Luisao

Reputation: 505

How to generate a request example in Swagger with Quarkus

I want to generate an Example Value in the request with Quarkus and Swagger.

Is there any annotation like @ApiModelProperty in Quarkus? Or is there any tag to set the example in the request?

enter image description here

Thanks

Upvotes: 2

Views: 2513

Answers (2)

Giacomo Venturini
Giacomo Venturini

Reputation: 455

You can use @Schema annotation over a field to define its openapi example.

import org.eclipse.microprofile.openapi.annotations.media.Schema;

public class Fruit {

    @Schema(example = "apple")
    public String name;

    @Schema(example = "the red fruit")
    public String description;
}

This will produce the following swagger:

swagger with example values

The annotation can be found into org.eclipse.microprofile.openapi:microprofile-openapi-api:X.X dependency.

Upvotes: 0

jcompetence
jcompetence

Reputation: 8383

For Quarkus you will need to use Microprofile Openapi Annotations:

https://download.eclipse.org/microprofile/microprofile-open-api-1.0/microprofile-openapi-spec.html

Specifically: @ExampleObject which

Illustrates an example of a particular content.

https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java

Example:

 public interface ExamplePayloads {
      String NEW_PLAYER = "{\"age\":12, \"username\":\"username\"}";
      String SAVED_PLAYER = "{\"id\":1234, \"age\":12, \"username\":\"username\"}";
      
}

The value attribute of ExampleObject takes a String:

   /**
     * A string representation of the example.
     * <p>
     * This is mutually exclusive with the externalValue property, and ignored if the externalValue property is
     * specified.
     * </p>
     * If the media type associated with the example allows parsing into an object, it may be converted from a string.
     * 
     * @return the value of the example
     **/
    String value() default "";
    
  

import static yourpackage.ExamplePayloads.*;

@Path("/players")
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON)
public class PlayersResource {


      @POST
      @Operation(summary = "save new player", description = "Creates new player with given age and username.")
      @RequestBody(
        required = true,
        content = @Content(
          schema = @Schema(implementation = Player.class, required = true, requiredProperties = {"username", "age"}),
          examples = @ExampleObject(
            name = "new player",
            description = "saves new player with parameters username and age",
            value = NEW_PLAYER
          )
        ))
      @APIResponses(
        value = {
        @APIResponse(
          name = "success",
          responseCode = "200",
          content = @Content(
            schema = @Schema(implementation = Player.class, required = true, requiredProperties = {"id", "username", "age"}),
            examples = @ExampleObject(
              name = "saved player",
              description = "new player with id assigned.",
              value = SAVED_PLAYER
            )
          ))
        ,
        @APIResponse(
          name = "bad request, no username",
          responseCode = "400",
          description = "missing username or age"
        ),
        }
    )
      public Player savePlayer(Player player) {
       
        return playersService.savePlayer(player);
      }


}

Upvotes: 3

Related Questions