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

@POST
@Path("migrate/{id}/{configurationVersion}")
@Operation(operationId = "migrateComponent",
        description = "Allows to migrate a component configuration without calling any component execution.")
@APIResponse(responseCode = "200",
        description = "the new configuration for that component (or the same if no migration was needed).",
        content = @Content(mediaType = APPLICATION_JSON))
@APIResponse(responseCode = "404", description = "The component is not found",
        content = @Content(mediaType = APPLICATION_JSON,
                schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
Map<String, String> migrate(
        @PathParam("id") @Parameter(name = "id", description = "the component identifier", in = PATH) String id,
        @PathParam("configurationVersion") @Parameter(name = "configurationVersion",
                description = "the configuration version you send", in = PATH) int version,
        @RequestBody(description = "the actual configuration in key/value form.", required = true,
                content = @Content(mediaType = APPLICATION_JSON,
                        schema = @Schema(type = OBJECT))) Map<String, String> config);
 

@POST
@Consumes(MediaType.TEXT_PLAIN)
@Produces(MediaType.TEXT_PLAIN)
@Callbacks({
        @Callback(name = "extendedCallback", callbackUrlExpression = "http://localhost:8080/resources/ext-callback", operations = @CallbackOperation(summary = "Get results", extensions = {
                @Extension(name = "x-object", value = "{ \"key\":\"value\" }", parseValue = true),
                @Extension(name = "x-object-unparsed", value = "{ \"key\":\"value\" }"),
                @Extension(name = "x-array", value = "[ \"val1\",\"val2\" ]", parseValue = true),
                @Extension(name = "x-booltrue", value = "true", parseValue = true),
                @Extension(name = "x-boolfalse", value = "false", parseValue = true),
                @Extension(name = "x-number", value = "42", parseValue = true),
                @Extension(name = "x-number-sci", value = "42e55", parseValue = true),
                @Extension(name = "x-positive-number-remains-string", value = "+42", parseValue = true),
                @Extension(name = "x-negative-number", value = "-42", parseValue = true),
                @Extension(name = "x-unparsable-number", value = "-Not.A.Number", parseValue = true)
        }, method = "get", responses = @APIResponse(responseCode = "200", description = "successful operation", content = @Content(mediaType = "application/json", schema = @Schema(type = SchemaType.ARRAY, implementation = String.class)))))
})
public String get(String data) {
    return data;
}
 

@POST
@Path("/createWithArray")
@APIResponse(
        description = "successful operation"
    )
@Operation(
    summary = "Creates list of users with given input array"
)
public Response createUsersWithArrayInput(
    @Parameter(
        description = "List of user object",
        required = true
        ) User[] users) {
            for (User user : users) {
                userData.addUser(user);
        }
    return Response.ok().entity("").build();
}
 

@Operation(
        operationId = "ListLegumes",
        summary = "List all legumes"
)
@APIResponse(
        responseCode = "200",
        description = "The List with all legumes"
)
@APIResponse(
        name = "notFound",
        responseCode = "404",
        description = "Legume list not found"
)
@APIResponse(
        name = "internalError",
        responseCode = "500",
        description = "Internal Server Error"
)
@GET
List<Legume> list();
 

@POST
@Path("/init")
@Operation(
        operationId = "ProvisionLegumes",
        summary = "Add default legumes to the Database"
)
@APIResponse(
        responseCode = "201",
        description = "Default legumes created"
)
@APIResponse(
        name = "notFound",
        responseCode = "404",
        description = "Legume provision not found"
)
@APIResponse(
        name = "internalError",
        responseCode = "500",
        description = "Internal Server Error"
)
Response provision();
 

@GET
@Path("component/{id}")
@Produces(MediaType.APPLICATION_JSON)
@Operation(
        description = "Returns an asciidoctor version of the documentation for the component represented by its identifier `id`.")
@APIResponse(responseCode = "200",
        description = "the list of available and storable configurations (datastore, dataset, ...).",
        content = @Content(mediaType = APPLICATION_JSON))
@APIResponse(responseCode = "404",
        description = "If the component is missing, payload will be an ErrorPayload with the code PLUGIN_MISSING.",
        content = @Content(mediaType = APPLICATION_JSON,
                schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
DocumentationContent getDocumentation(
        @PathParam("id") @Parameter(name = "id", description = "the component identifier", in = PATH) String id,
        @QueryParam("language") @DefaultValue("en") @Parameter(name = "language",
                description = "the language for display names.", in = QUERY,
                schema = @Schema(type = STRING, defaultValue = "en")) String language,
        @QueryParam("segment") @DefaultValue("ALL") @Parameter(name = "segment",
                description = "the part of the documentation to extract.", in = QUERY,
                schema = @Schema(type = STRING, defaultValue = "ALL")) DocumentationSegment segment);
 

@POST
@Path("/createWithList")
@APIResponse(
        description = "successful operation"
    )
@Operation(
    summary = "Creates list of users with given input array"
)
public Response createUsersWithListInput(
    @Parameter(
        description = "List of user object",
        required = true) java.util.List<User> users) {
            for (User user : users) {
                userData.addUser(user);
            }
            return Response.ok().entity("").build();
        }
 

@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();
}
 

@PUT
@Path("{id}")
@Consumes("application/json")
@Produces("text/plain")
@APIResponse(
        responseCode="200",
        description="Booking updated"
        )
@APIResponse(
        responseCode="404",
        description="Booking not found"
        )
@Operation(
    summary="Update a booking with ID",
    operationId = "updateBookingId")
public Response updateBooking(
    @PathParam("id") int id, Booking booking){
        if(bookings.get(id)!=null){
            bookings.put(id, booking);
            return Response.ok().build();
        }
        else{
            return Response.status(Status.NOT_FOUND).build();
        }
    }
 

@DELETE
@Path("{id}")
@Tag()
@APIResponse(
        responseCode="200",
        description="Booking deleted successfully."
    )
@APIResponse(
        responseCode="404",
        description="Booking not found."
    )
@Operation(
    summary="Delete a booking with ID",
    operationId = "deleteBookingById")
@Produces("text/plain")
public Response deleteBooking(
        @PathParam("id") int id){
            if(bookings.get(id)!=null) {
                bookings.remove(id);
                return Response.ok().build();
            }
            else {
                return Response.status(Status.NOT_FOUND).build();
            }
        }
 

@GET
@Path("index")
@Operation(operationId = "getComponentIndex", description = "Returns the list of available components.")
@APIResponse(responseCode = "200", description = "The index of available components.",
        content = @Content(mediaType = APPLICATION_OCTET_STREAM))
ComponentIndices getIndex(
        @QueryParam("language") @DefaultValue("en") @Parameter(name = "language",
                description = "the language for display names.", in = QUERY,
                schema = @Schema(type = STRING, defaultValue = "en")) String language,
        @QueryParam("includeIconContent") @DefaultValue("false") @Parameter(name = "includeIconContent",
                description = "should the icon binary format be included in the payload.", in = QUERY,
                schema = @Schema(type = STRING, defaultValue = "en")) boolean includeIconContent,
        @QueryParam("q") @Parameter(name = "q",
                description = "Query in simple query language to filter components. "
                        + "It provides access to the component `plugin`, `name`, `id` and `metadata` of the first configuration property. "
                        + "Ex: `(id = AYETAE658349453) AND (metadata[configurationtype::type] = dataset) AND (plugin = jdbc-component) AND "
                        + "(name = input)`",
                in = QUERY, schema = @Schema(type = STRING)) String query);
 

@DELETE
@Path("{id}")
@APIResponse(
        responseCode="200",
        description="Review deleted"
        )
@APIResponse(
        responseCode="404",
        description="Review not found"
        )
@Operation(
    summary="Delete a Review with ID",
    operationId = "deleteReview"
    )
@Produces("text/plain")
public Response deleteReview(
        @PathParam("id") int id){
            if(reviews.get(id)!=null) {
                reviews.remove(id);
                return Response.ok().build();
            }
            else {
                return Response.status(Status.NOT_FOUND).build();
            }
        }
 

@POST
@Path("migrate/{id}/{configurationVersion}")
@Operation(operationId = "migrateConfiguration",
        description = "Allows to migrate a configuration without calling any component execution.")
@APIResponse(responseCode = "200",
        description = "the new values for that configuration (or the same if no migration was needed).",
        content = @Content(mediaType = APPLICATION_JSON))
@APIResponse(responseCode = "400",
        description = "If the configuration is missing, payload will be an ErrorPayload with the code CONFIGURATION_MISSING.",
        content = @Content(mediaType = APPLICATION_JSON,
                schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
@APIResponse(responseCode = "404", description = "The configuration is not found",
        content = @Content(mediaType = APPLICATION_JSON))
Map<String, String> migrate(
        @PathParam("id") @Parameter(name = "id", description = "the configuration identifier", in = PATH) String id,
        @PathParam("configurationVersion") @Parameter(name = "configurationVersion",
                description = "the configuration version you send", in = PATH) int version,
        @RequestBody(description = "the actual configuration in key/value form.", required = true,
                content = @Content(mediaType = APPLICATION_JSON,
                        schema = @Schema(type = OBJECT))) Map<String, String> config);
 

@GET
@Path("/logout")
@APIResponse(
            responseCode = "200",
            description = "Successful user logout."
            )
@ExternalDocumentation(
        description = "Policy on user security.",
        url = "http://exampleurl.com/policy"
        )
@Operation(
    summary = "Logs out current logged in user session",
    operationId = "logOutUser"
    /* tags = {"user"}, // intentionally removed to have a method with no tags */)
public Response logoutUser() {
return Response.ok().entity("").build();
}
 

@GET
@Path("/contacts")
@APIResponse(responseCode = "200",
        description = "Contact list response",
        name = "ContactListResponse"
)
public Response getContacts() {
    return Response.ok("This should be a contact list").build();
}
 

@GET
@Path("icon/{id}")
@Produces({ APPLICATION_JSON, APPLICATION_OCTET_STREAM })
@Operation(description = "Returns a particular component icon in raw bytes.")
@APIResponse(responseCode = "200", description = "The component icon in binary form.",
        content = @Content(mediaType = APPLICATION_OCTET_STREAM))
@APIResponse(responseCode = "404", description = "The family or icon is not found",
        content = @Content(mediaType = APPLICATION_JSON))
Response icon(@PathParam("id") @Parameter(name = "id", description = "the component icon identifier",
        in = PATH) String id);
 

@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();
        }
    }
 

@DELETE
@Path("/unnamed")
@APIResponse(responseCode = "204", description = "No content")
public Response deleteTaskWithoutParamName(
        @Parameter(description = "The id of the task", example = "e1cb23d0-6cbe-4a29", schema = @Schema(type = SchemaType.STRING)) @PathParam("taskId") String taskId,
        @QueryParam("nextTask") String nextTaskId) {
    return Response.noContent().build();
}
 

@GET
@Path("/logout")
@APIResponse(
        description = "successful operation"
    )
@Operation(
    summary = "Logs out current logged in user session"
)
public Response logoutUser() {
    return Response.ok().entity("").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();
        }
    }
 

@GET
@Path("index")
@Operation(operationId = "getActionIndex",
        description = "This endpoint returns the list of available actions for a certain family and potentially filters the "
                + "output limiting it to some families and types of actions.")
@APIResponse(responseCode = "200", description = "The action index.",
        content = @Content(mediaType = APPLICATION_JSON))
ActionList getIndex(
        @QueryParam("type") @Parameter(name = "type", in = QUERY,
                description = "the types of actions") String[] types,
        @QueryParam("family") @Parameter(name = "family", in = QUERY,
                description = "the families") String[] families,
        @QueryParam("language") @Parameter(name = "language", description = "the language to use", in = QUERY,
                schema = @Schema(defaultValue = "en", type = STRING)) @DefaultValue("en") String language);
 

@POST
@APIResponse(
        description = "successful operation"
    )
@Operation(
    summary = "Create user",
    description = "This can only be done by the logged in user."
)
@SecurityRequirements(
    value = {
        @SecurityRequirement(
            name = "userApiKey"
        ),
        @SecurityRequirement(
            name = "userBasicHttp"
        ),
        @SecurityRequirement(
            name = "userBearerHttp"
        )
    }
)
public Response createUser(
    @Parameter(
        description = "Created user object",
        schema = @Schema(ref = "#/components/schemas/User"),
        required = true
        ) User user) {
            userData.addUser(user);
            return Response.ok().entity("").build();
        }
 

@DELETE
@Path("{id}")
@Operation(
        operationId = "DeleteLegume",
        summary = "Delete a Legume"
)
@APIResponse(
        responseCode = "204",
        description = "Empty response"
)
@APIResponse(
        name = "notFound",
        responseCode = "404",
        description = "Legume not found"
)
@APIResponse(
        name = "internalError",
        responseCode = "500",
        description = "Internal Server Error"
)
Response delete(
        @Parameter(name = "id",
                description = "Id of the Legume to delete",
                required = true,
                example = "81471222-5798-11e9-ae24-57fa13b361e1",
                schema = @Schema(description = "uuid", required = true))
        @PathParam("id")
        @NotEmpty final String legumeId);
 

@GET
@Path("/inventory")
@Produces({"application/json", "application/xml"})
@APIResponse(
        responseCode = "200", 
        description = "successful operation"
    )
@Operation(
    summary = "Returns pet inventories by status", 
    description = "Returns a map of status codes to quantities"
)
public java.util.Map<String, Integer> getInventory() {
    return petData.getInventoryByStatus();
}
 

@POST
@Consumes(MediaType.TEXT_PLAIN)
@Produces(MediaType.TEXT_PLAIN)
@Callbacks({
        @Callback(name = "extendedCallback", callbackUrlExpression = "http://localhost:8080/resources/ext-callback", operations = @CallbackOperation(summary = "Get results", extensions = {
                @Extension(name = "x-object", value = "{ \"key\":\"value\" }", parseValue = true),
                @Extension(name = "x-object-unparsed", value = "{ \"key\":\"value\" }"),
                @Extension(name = "x-array", value = "[ \"val1\",\"val2\" ]", parseValue = true),
                @Extension(name = "x-booltrue", value = "true", parseValue = false)
        }, method = "get", responses = @APIResponse(responseCode = "200", description = "successful operation", content = @Content(mediaType = "application/json", schema = @Schema(type = SchemaType.ARRAY, implementation = String.class)))))
})
public String get(String data) {
    return data;
}
 

@GET
@Path("details") // bulk mode to avoid to fetch components one by one when reloading a pipeline/job
@Operation(operationId = "getComponentDetail",
        description = "Returns the set of metadata about a few components identified by their 'id'.")
@APIResponse(responseCode = "200", description = "the list of details for the requested components.",
        content = @Content(mediaType = APPLICATION_JSON))
@APIResponse(responseCode = "400", description = "Some identifiers were not valid.",
        content = @Content(mediaType = APPLICATION_JSON,
                schema = @Schema(type = OBJECT, implementation = SampleErrorForBulk.class)))
ComponentDetailList getDetail(
        @QueryParam("language") @DefaultValue("en") @Parameter(name = "language",
                description = "the language for display names.", in = QUERY,
                schema = @Schema(type = STRING, defaultValue = "en")) String language,
        @QueryParam("identifiers") @Parameter(name = "identifiers",
                description = "the component identifiers to request.", in = QUERY) String[] ids);
 

@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];
}
 

@Path("{id}")
@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "Returns an AbstractPet with a discriminator declared in the response, "
        + "no property name (invalid OpenAPI document)")
@APIResponse(content = {
        @Content(schema = @Schema(oneOf = { Cat.class, Dog.class, Lizard.class }, discriminatorMapping = {
                @DiscriminatorMapping(value = "dog", schema = Dog.class) }))
})
@SuppressWarnings("unused")
public AbstractPet get(@PathParam("id") String id) {
    return null;
}
 

@Path("{id}")
@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "Returns an AbstractPet with a discriminator declared in the response, "
        + "no mapping due to empty @DiscriminatorMapping")
@APIResponse(content = {
        @Content(schema = @Schema(oneOf = { Cat.class, Dog.class,
                Lizard.class }, discriminatorProperty = "pet_type", discriminatorMapping = { @DiscriminatorMapping }))
})
@SuppressWarnings("unused")
public AbstractPet get(@PathParam("id") String id) {
    return null;
}
 

@GET
@Path("/findByTags")
@Produces("application/json")
@Callback(
    name = "tagsCallback",
    callbackUrlExpression = "http://petstoreapp.com/pet",
    operations = @CallbackOperation(
        method = "GET",
        summary = "Finds Pets by tags",
        description = "Find Pets by tags; Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.",
        responses = {
            @APIResponse(
                responseCode = "400",
                description = "Invalid tag value",
                content = @Content(mediaType = "none")
            ),
            @APIResponse(
                responseCode = "200",
                content = @Content(
                    mediaType = "application/json",
                    schema = @Schema(type = SchemaType.ARRAY, implementation = Pet.class))
                )
        }
    )
)
@APIResponseSchema(Pet[].class)
@Deprecated
public Response findPetsByTags(
    @HeaderParam("apiKey") String apiKey,
    @Parameter(
        name = "tags",
        description = "Tags to filter by",
        required = true,
        deprecated = true,
        schema = @Schema(implementation = String.class, deprecated = true,
          externalDocs = @ExternalDocumentation(description = "Pet Types", url = "http://example.com/pettypes"),
          enumeration = { "Cat", "Dog", "Lizard" }, defaultValue = "Dog" ))
    @QueryParam("tags") String tags) {
        return Response.ok(petData.findPetByTags(tags)).build();
    }