org.eclipse.microprofile.openapi.annotations.responses.APIResponses Java Examples

@APIResponses(
        value = {
            @APIResponse(
                    responseCode = "404",
                    description = "We could not find anything",
                    content = @Content(mediaType = "text/plain"))
            ,
    @APIResponse(
                    responseCode = "200",
                    description = "We have a list of books",
                    content = @Content(mediaType = "application/json",
                            schema = @Schema(implementation = Properties.class)))})
@Operation(summary = "Outputs a list of books",
        description = "This method outputs a list of books")
@Timed(name = "get-all-books",
        description = "Monitor the time getAll Method takes",
        unit = MetricUnits.MILLISECONDS,
        absolute = true)
@GET
public Response getAll() {
    return Response.ok(bookService.getAll()).build();
}
 

@Consumes({ MediaType.APPLICATION_JSON })
@POST
@Operation(
    summary = "Create new item",
    description = "Post operation with entity in a body"
)
@APIResponses(
    @APIResponse(
        content = @Content(
            schema = @Schema(implementation = Item.class), 
            mediaType = MediaType.APPLICATION_JSON
        ),
        headers = @Header(name = "Location"),
        responseCode = "201"
    )
)
public Response createItem(
    @Context final UriInfo uriInfo,
    @Parameter(required = true) final Item item) {
    items.put(item.getName(), item);
    return Response
        .created(uriInfo.getBaseUriBuilder().path(item.getName()).build())
        .entity(item).build();
}
 

@Produces({ MediaType.APPLICATION_JSON })
@Path("/{name}")
@GET
@Operation(
    summary = "Get item by name",
    description = "Get operation with type and headers"
)
@APIResponses({
    @APIResponse(content = @Content(schema = @Schema(implementation = Item.class)), responseCode = "200"),
    @APIResponse(responseCode = "404")
})
public Response getItem(
        @Parameter(required = true) @HeaderParam("Accept-Language") final String language,
        @Parameter(required = true) @PathParam("name") String name) {
    return items.containsKey(name) 
        ? Response.ok().entity(items.get(name)).build() 
            : Response.status(Status.NOT_FOUND).build();
}
 

/**
 * Perform a GET operation on an LDP Resource.
 *
 * @implNote The Memento implemenation pattern exactly follows
 *           <a href="https://tools.ietf.org/html/rfc7089#section-4.2.1">section 4.2.1 of RFC 7089</a>.
 * @param uriInfo the URI info
 * @param headers the HTTP headers
 * @param request the request
 * @return the async response
 */
@GET
@Timed
@Operation(summary = "Get a linked data resource")
@APIResponses(
    value = {
        @APIResponse(
            responseCode = "404",
            description = "Missing resource"),
        @APIResponse(
            responseCode = "200",
            description = "The linked data resource, serialized as Turtle",
            content = @Content(mediaType = "text/turtle")),
        @APIResponse(
            responseCode = "200",
            description = "The linked data resource, serialized as JSON-LD",
            content = @Content(mediaType = "application/ld+json"))})
public CompletionStage<Response> getResource(@Context final Request request, @Context final UriInfo uriInfo,
        @Context final HttpHeaders headers) {
    return fetchResource(new TrellisRequest(request, uriInfo, headers))
        .thenApply(ResponseBuilder::build).exceptionally(this::handleException);
}
 

@GET
@Path("/openapi/responses/{version}")
@Produces("application/json")
@APIResponses({
        @APIResponse(content = @Content(mediaType = "application/json", schema = @Schema(type = SchemaType.OBJECT, implementation = MyOpenApiEntityV1.class))),
        @APIResponse(content = @Content(mediaType = "application/json", schema = @Schema(type = SchemaType.OBJECT, implementation = MyOpenApiEntityV2.class)))
})
public Response openApiResponses(@PathParam("version") String version) {
    if ("v1".equals(version)) {
        MyOpenApiEntityV1 entityV1 = new MyOpenApiEntityV1();
        entityV1.setName("my openapi entity version one name");
        return Response.ok(entityV1).build();
    }

    MyOpenApiEntityV2 entityV2 = new MyOpenApiEntityV2();
    entityV2.setName("my openapi entity version two name");
    entityV2.setValue(version);
    return Response.ok(entityV2).build();
}
 

@GET
@Tag(ref="bookings")
@APIResponses(value={
        @APIResponse(
                responseCode="200",
                description="Bookings retrieved",
                content=@Content(
                    schema=@Schema(
                        type = SchemaType.ARRAY,
                        implementation=Booking.class))
                ),
            @APIResponse(
                responseCode="404",
                description="No bookings found for the user.")
})
@Operation(
    summary="Retrieve all bookings for current user",
    operationId = "getAllBookings")
@Produces("application/json")
public Response getBookings(){
    return Response.ok().entity(bookings.values()).build();
}
 

@GET
@APIResponses(value = {
	@APIResponse(
      responseCode = "404",
      description = "Author Not Found"
    ),
    @APIResponse(
      responseCode = "200",
      description = "Author with requested name",
      content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = Author.class)
      )
    ),
    @APIResponse(
      responseCode = "500",
      description = "Internal service error"  	      
    )
})
@Operation(
	    summary = "Get specific author",
	    description = "Get specific author"
)
public Response getAuthor(@Parameter(
           description = "The unique name of the author",
           required = true,
           example = "Niklas Heidloff",
           schema = @Schema(type = SchemaType.STRING))
		@QueryParam("name") String name) {
			
		System.out.println("com.ibm.authors.GetAuthor.getAuthor /getauthor invoked");
	
		Author author = new Author();
		author.name = "Niklas Heidloff";
		author.twitter = "https://twitter.com/nheidloff";
		author.blog = "http://heidloff.net";

		return Response.ok(this.createJson(author)).build();
}
 

@Produces({ MediaType.APPLICATION_JSON })
@GET
@Operation(
    summary = "Get all items",
    description = "Get operation with Response and @Default value"
)
@APIResponses(
    @APIResponse(
        content = @Content(schema = @Schema(implementation = Item.class, type = SchemaType.ARRAY)),
        responseCode = "200"
    )
)
public Response getItems(@Parameter(required = true) @QueryParam("page") @DefaultValue("1") int page) {
    return Response.ok(items.values()).build();
}
 

@DELETE
@Path("/{username}")
@APIResponses(value={
        @APIResponse(
                responseCode = "400",
                description = "Invalid username supplied"
            ),
            @APIResponse(
                responseCode = "404",
                description = "User not found"
            )
})
@Operation(
    summary = "Delete user",
    description = "This can only be done by the logged in user."
)
public Response deleteUser(
    @Parameter(
        name = "username",
        description = "The name that needs to be deleted",
        schema = @Schema(type = SchemaType.STRING),
        required = true
    )
    @PathParam("username") String username) {
        if (userData.removeUser(username)) {
            return Response.ok().entity("").build();
        }
        else {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
    }
 

@PUT
@Consumes({"application/json", "application/xml"})
@SecurityRequirement(
        name = "petsHttp"
    )
@APIResponses(value={
        @APIResponse(
                responseCode = "400",
                description = "Invalid ID supplied",
                content = @Content(mediaType = "application/json")
            ),
            @APIResponse(
                responseCode = "404",
                description = "Pet not found",
                content = @Content(mediaType = "application/json")
            ),
            @APIResponse(
                responseCode = "405",
                description = "Validation exception",
                content = @Content(mediaType = "application/json")
            )
})
@Operation(
    summary = "Update an existing pet",
    description = "Update an existing pet with the given new attributes"
)
public Response updatePet(
    @Parameter(
        name ="petAttribute",
        description = "Attribute to update existing pet record",
        required = true,
        schema = @Schema(implementation = Pet.class)) Pet pet) {
            Pet updatedPet = petData.addPet(pet);
            return Response.ok().entity(updatedPet).build();
        }
 

@GET
@Path("/{username}")
@Tag(ref="user")
@APIResponses(value={
        @APIResponse(
                responseCode = "200",
                description = "Successfully retrieved user by user name.",
                content = @Content(
                    schema = @Schema(implementation = User.class)
                )),
            @APIResponse(
                responseCode = "400",
                description = "Invalid username supplied",
                content = @Content(
                        schema = @Schema(implementation = User.class)
                ))
})
@Operation(
    summary = "Get user by user name",
    operationId = "getUserByName")
public Response getUserByName(
    @Parameter(
        name = "username",
        schema = @Schema(type = SchemaType.STRING),
        required = true
        )
    @PathParam("username") String userName) throws NotFoundException {
        User user = userData.findUserByName(userName);
        if (null != user) {
            return Response.ok().entity(user).build();
        }
        else {
            throw new NotFoundException("User not found");
        }
    }
 

@GET
@Path("{id}")
@Parameters(
    {
        @Parameter(
                    name = "id",
                    description = "ID of the booking",
                    required = true,
                    in = ParameterIn.PATH,
                    style = ParameterStyle.SIMPLE
                )
        }
        )

@Produces("application/json")
@Operation(
    summary="Get a booking with ID",
    operationId = "getBookingById")
@APIResponses(value={
        @APIResponse(
                responseCode="200",
                description="Booking retrieved",
                content=@Content(
                    schema=@Schema(
                        implementation=Booking.class))),
        @APIResponse(
                responseCode="404",
                description="Booking not found")
})
public Response getBooking(
    @PathParam("id") int id){
        Booking booking = bookings.get(id);
        if(booking!=null){
            return Response.ok().entity(booking).build();
        }
        else{
            return Response.status(Status.NOT_FOUND).build();
        }
    }
 

@POST
@Consumes("application/json")
@Produces("application/json")
@Operation(summary = "Convert an array of integer types to an array of floating point types")
@RequestBody(content = @Content(schema = @Schema(anyOf = { int[].class, long[].class })))
@APIResponses({
        @APIResponse(responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(oneOf = {
                float[].class, double[].class }))) })
public Object intToFloat(@SuppressWarnings("unused") Object input) {
    return null;
}
 

@POST
@Consumes("application/json")
@Produces("application/json")
@Operation(summary = "Convert an array of doubles to an array of floats")
@APIResponses({
        @APIResponse(responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = float[].class))) })
public float[] doubleToFloat(@SuppressWarnings("unused") double[] input) {
    return new float[0];
}
 

@GET
@Operation(summary = "Get an object containing a primitive array")
@APIResponses({
        @APIResponse(responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = PrimitiveArrayTestObject.class))) })
public PrimitiveArrayTestObject getResponse() {
    return new PrimitiveArrayTestObject();
}
 

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@APIResponses(/* Intentionally left blank */)
public Pet createOrUpdatePet(Pet pet) {
    return pet;
}
 

@Path("/{username}")
  @PUT
  @RequestBody(
          name = "user",
          description = "Record of a new user to be created in the system.",
          content = @Content(
              mediaType = "application/json",
              schema = @Schema(implementation = User.class),
              examples = @ExampleObject(
                  name = "user",
                  summary = "Example user properties to update",
                  value = "Properties to update in JSON format here"
              )
          )
      )
  @Operation(
    summary = "Update user",
    description = "This can only be done by the logged in user.",
    operationId = "updateUser")
@APIResponses(value={
        @APIResponse(
                responseCode = "200",
                description = "User updated successfully",
                content = @Content(
                    schema = @Schema(ref="User"),
                    encoding = @Encoding(
                        name = "password",
                        contentType = "text/plain",
                        style = "form",
                        allowReserved = true,
                        explode = true,
                        headers = @Header(ref="Max-Rate")
                        )
                    )
            ),
            @APIResponse(
                responseCode = "400",
                description = "Invalid user supplied"
            ),
            @APIResponse(
                responseCode = "404",
                description = "User not found"
            )
})
@Tag(ref="user")
public Response updateUser(
    @Parameter(
        name = "username",
        description = "User that needs to be updated",
        schema = @Schema(type = SchemaType.STRING),
        required = true
        )
    @PathParam("username") String username,
    User user) {
            userData.addUser(user);
            return Response.ok().entity("").build();
        }
 

@GET
@Path("users/{user}")
@Operation(
    operationId = "getReviewByUser",
    summary="Get all reviews by user")
@APIResponses(value={
        @APIResponse(
                responseCode="200",
                description="Review(s) retrieved",
                content=@Content(
                    schema=@Schema(
                        implementation=Review.class))),
        @APIResponse(
                responseCode="404",
                description="Review(s) not found")
})
@Produces("application/json")
public Response getReviewByUser(
    @Parameter(
        name = "user",
        description = "username of the user for the reviews",
        required = true,
        in = ParameterIn.PATH,
        content = @Content(
            examples = @ExampleObject(
                name = "example",
                value = "bsmith")),
        examples = { @ExampleObject(name="example1", value="bsmith"), @ExampleObject(name="example2", value="[email protected]")})
    @PathParam("user") String user){

        List<Review> reviewsByUser = new ArrayList<Review>();
        for (Review review : reviews.values()) {
            User currentUser = review.getUser();
            if (currentUser.getUserName() == user) {
                reviewsByUser.add(review);
            }
        }
        if(!reviewsByUser.isEmpty()){
            return Response.ok().entity(reviewsByUser).build();
        }
        else{
            return Response.status(Status.NOT_FOUND).build();
        }
}
 

@GET
@Path("/{petId}")
@APIResponses(value={
        @APIResponse(
                responseCode = "400",
                description = "Invalid ID supplied",
                content = @Content(
                    mediaType = "none")
            ),
            @APIResponse(
                responseCode = "404",
                description = "Pet not found",
                content = @Content(
                    mediaType = "none")
            ),
            @APIResponse(
                responseCode = "200",
                content = @Content(
                    mediaType = "application/json",
                    schema = @Schema(type = SchemaType.OBJECT, implementation = Pet.class, 
                      oneOf = { Cat.class, Dog.class, Lizard.class }, 
                      readOnly = true))
            )
})
@Operation(
        summary = "Find pet by ID",
        description = "Returns a pet when ID is less than or equal to 10"
)
public Response getPetById(
    @Parameter(
        name = "petId",
        description = "ID of pet that needs to be fetched",
        required = true,
        example = "1",
        schema = @Schema(
            implementation = Long.class,
            maximum = "101",
            exclusiveMaximum = true,
            minimum = "9",
            exclusiveMinimum = true, 
            multipleOf = 10))
    @PathParam("petId") Long petId)
throws NotFoundException {
    Pet pet = petData.getPetById(petId);
    if (pet != null) {
        return Response.ok().entity(pet).build();
    }
    else {
        throw new NotFoundException(404, "Pet not found");
    }
}
 

@GET
@Path("/{petId}/download")
@APIResponses(value={
        @APIResponse(
                responseCode = "400",
                description = "Invalid ID supplied",
                content = @Content(mediaType = "none")
            ),
            @APIResponse(
                responseCode = "404",
                description = "Pet not found",
                content = @Content(mediaType = "none")
            )
})
@Operation(
    summary = "Find pet by ID and download it",
    description = "Returns a pet when ID is less than or equal to 10"
)
public Response downloadFile(
    @Parameter(
        name = "petId",
        description = "ID of pet that needs to be fetched",
        required = true,
        schema = @Schema(
            implementation = Long.class,
            maximum = "10",
            minimum = "1")
    )
    @PathParam("petId") Long petId)
throws NotFoundException {
    StreamingOutput stream = new StreamingOutput() {
        @Override
        public void write(OutputStream output) throws IOException {
            try {
                // TODO: write file content to output;
                output.write("hello, world".getBytes());
            }
            catch (Exception e) {
                e.printStackTrace();
            }
        }
    };
    return Response.ok(stream, "application/force-download")
    .header("Content-Disposition", "attachment; filename = foo.bar")
    .build();
}
 

@DELETE
@Path("/{petId}")
@SecurityRequirement(
        name = "petsOAuth2",
        scopes = "write:pets"
        )
@APIResponses(value = {
        @APIResponse(
                responseCode = "400",
                description = "Invalid ID supplied"
            ),
            @APIResponse(
                responseCode = "404",
                description = "Pet not found"
            )
})
@Operation(
    summary = "Deletes a pet by ID",
    description = "Returns a pet when ID is less than or equal to 10"
)
public Response deletePet(
    @Parameter(
        name = "apiKey",
        description = "authentication key to access this method",
        schema = @Schema(type = SchemaType.STRING, implementation = String.class,
          maxLength = 256, minLength = 32))
    @HeaderParam("api_key") String apiKey,
    @Parameter(
        name = "petId",
        description = "ID of pet that needs to be fetched",
        required = true,
        schema = @Schema(
            implementation = Long.class,
            maximum = "10",
            minimum = "1"))
    @PathParam("petId") Long petId) {
        if (petData.deletePet(petId)) {
            return Response.ok().build();
        }
        else {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
    }
 

@GET
@APIResponses({ @APIResponse(responseCode = "204", description = "APIResponses with a no content response") })
@Path("/openapi/no-content/api-responses")
public Response apiResponsesNoContent() {
    return Response.noContent().build();
}
 

@GET
@Path("/{username}")
@APIResponses(value={
        @APIResponse(
                responseCode = "200",
                description = "successful operation",
                content = @Content(
                    schema = @Schema(implementation = User.class)
                )
            ),
        @APIResponse(
                responseCode = "400",
                description = "Invalid username supplied",
                content = @Content(
                    schema = @Schema(implementation = User.class)
                )
            ),
        @APIResponse(
                responseCode = "404",
                description = "User not found",
                content = @Content(
                    schema = @Schema(implementation = User.class)
                )
            )
})
@Operation(
    summary = "Get user by user name"
)
public Response getUserByName(
    @Parameter(
        name = "username",
        description = "The name that needs to be fetched. Use user1 for testing.",
        schema = @Schema(type = SchemaType.STRING),
        required = true
    )
    @PathParam("username") String username) throws ApiException {
        User user = userData.findUserByName(username);
        if (null != user) {
            return Response.ok().entity(user).build();
        }
        else {
            throw new NotFoundException(404, "User not found");
        }
    }