org.eclipse.microprofile.openapi.annotations.Operation 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);
 

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

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

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

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

@GET
@APIResponse(
        responseCode = "200",
        description = "successful operation",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(
                type = SchemaType.ARRAY,
                implementation = Review.class
            )
        ),
        headers = @Header(ref="#/components/headers/Request-Limit")
    )
@Operation(
    operationId = "getAllReviews",
    summary = "get all the reviews"
)
@Produces("application/json")
public Response getAllReviews(){
    return Response.ok().entity(reviews.values()).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();
}
 

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

@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("details")
@Operation(operationId = "getConfigurationDetail",
        description = "Returns all available configuration type - storable models. "
                + "Note that the lightPayload flag allows to load all of them at once when you eagerly need "
                + " to create a client model for all configurations.")
@APIResponse(responseCode = "200",
        description = "the list of available and storable configurations (datastore, dataset, ...).",
        content = @Content(mediaType = APPLICATION_JSON))
ConfigTypeNodes 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 comma separated list of identifiers to request.", in = QUERY) String[] ids);
 

@GET
@Path("index")
@Operation(description = "Returns all available configuration type - storable models. "
        + "Note that the lightPayload flag allows to load all of them at once when you eagerly need "
        + " to create a client model for all configurations.")
@APIResponse(responseCode = "200",
        description = "the list of available and storable configurations (datastore, dataset, ...).",
        content = @Content(mediaType = APPLICATION_JSON))
ConfigTypeNodes getRepositoryModel(
        @QueryParam("language") @DefaultValue("en") @Parameter(name = "language",
                description = "the language for display names.", in = QUERY,
                schema = @Schema(type = STRING, defaultValue = "en")) String language,
        @QueryParam("lightPayload") @DefaultValue("true") @Parameter(name = "lightPayload",
                description = "should the payload skip the forms and actions associated to the configuration.",
                in = QUERY, schema = @Schema(type = BOOLEAN, defaultValue = "true")) boolean lightPayload,
        @QueryParam("q") @Parameter(name = "q",
                description = "Query in simple query language to filter configurations. "
                        + "It provides access to the configuration `type`, `name`, `type` and "
                        + "first configuration property `metadata`. "
                        + "See component index endpoint for a syntax example.",
                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();
            }
        }
 

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

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

@POST
@Path("/order")
@Operation(
    summary = "Place an order for a pet"
)
@APIResponse(
        responseCode = "200", 
        description = "successful operation"
    )
@APIResponse(
        responseCode = "400", 
        description = "Invalid Order"
        ) 
public Order placeOrder(
    @Parameter(
        description = "order placed for purchasing the pet",
        required = true
    ) 
    Order order) {
        storeData.placeOrder(order);
        return storeData.placeOrder(order);
    }
 

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

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

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

@POST
@Consumes({"application/json", "application/xml"})
@Produces({"application/json", "application/xml"})
@SecurityRequirement(
        name = "petsApiKey"
    )
@APIResponse(
        responseCode = "400",
        description = "Invalid input",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = ApiResponse.class))
    )
@RequestBody(
        name="pet",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = Pet.class), 
            examples = @ExampleObject(ref = "http://example.org/petapi-examples/openapi.json#/components/examples/pet-example") ),
        required = true,
        description = "example of a new pet to add"
    )
@Operation(
    summary = "Add pet to store",
    description = "Add a new pet to the store"
)
public Response addPet(Pet pet) {
            Pet updatedPet = petData.addPet(pet);
            return Response.ok().entity(updatedPet).build();
        }
 

@GET
@Path("/now")
@Produces(MediaType.APPLICATION_JSON)
@Tag(name = "time", description = "time service methods")
@ExternalDocumentation(description = "Basic World Clock API Home.",
        url = "http://worldclockapi.com/")
@Operation(summary = "Queries the WorldClockApi using the MP-RestClient",
        description = "Uses the WorldClockApi type proxy injected by the MP-RestClient to access the worldclockapi.com service")
public Now utc() {
    return clockApi.utc();
}
 

@GET
@Path("/login")
@APIResponse(
        responseCode = "200",
        description = "successful operation",
        content = @Content(
            schema = @Schema(implementation = String.class)
        )
    )
@APIResponse(
        responseCode = "400",
        description = "Invalid username/password supplied",
        content = @Content(
            schema = @Schema(implementation = String.class)
        )
    )
@Operation(
    summary = "Logs user into the system"
)
public Response loginUser(
    @Parameter(
        name = "username",
        description = "The user name for login",
        schema = @Schema(type = SchemaType.STRING),
        required = true
    )
    @QueryParam("username") String username,
    @Parameter(
        name = "password",
        description = "The password for login in clear text",
        schema = @Schema(type = SchemaType.STRING),
        required = true)
    @QueryParam("password") String password) {
        return Response.ok()
        .entity("logged in user session:" + System.currentTimeMillis())
        .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();
}
 

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

@DELETE
  @Path("/{username}")
  @Tag(ref="user")
  @APIResponse(
          responseCode = "200",
          description = "User deleted successfully"
          )
  @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.",
    operationId = "deleteUser")
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("dependencies")
@Operation(description = "Returns a list of dependencies for the given components. "
        + "IMPORTANT: don't forget to add the component itself since it will not be part of the dependencies."
        + "Then you can use /dependency/{id} to download the binary.")
@APIResponse(responseCode = "200", description = "The list of dependencies per component",
        content = @Content(mediaType = APPLICATION_JSON))
Dependencies getDependencies(@QueryParam("identifier") @Parameter(name = "identifier",
        description = "the list of component identifiers to find the dependencies for.", in = QUERY) String[] ids);
 

@GET
@Path("dependency/{id}")
@Produces(MediaType.APPLICATION_OCTET_STREAM)
@Operation(description = "Return a binary of the dependency represented by `id`. "
        + "It can be maven coordinates for dependencies or a component id.")
@APIResponse(responseCode = "200", description = "The dependency binary (jar).",
        content = @Content(mediaType = APPLICATION_OCTET_STREAM))
@APIResponse(responseCode = "404",
        description = "If the plugin is missing, payload will be an ErrorPayload with the code PLUGIN_MISSING.",
        content = @Content(mediaType = APPLICATION_JSON,
                schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
StreamingOutput getDependency(@PathParam("id") @Parameter(name = "id", description = "the dependency binary (jar).",
        in = PATH) String id);
 

@POST
@Path("/createWithList")
@Tag(ref="user")
@Tags(refs="create")
@APIResponse(
        responseCode = "200",
        description = "Successfully created list of users."
        )
@APIResponse(
        responseCode = "400",
        description = "Unable to create list of users."
        )
@Operation(
    summary = "Creates list of users with given input list", //List of User objects
    operationId = "createUsersFromList"
    )
  public Response createUsersWithListInput(
        @RequestBody(
            description = "List of user object",
            required = true
        )
        java.util.List<User> users) {
            for (User user : users) {
                userData.addUser(user);
            }
            return Response.ok().entity("").build();
        }
 

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

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