io.swagger.v3.oas.annotations.Operation Java Examples

/**
 * {@value GET_SPECIFIC_DESC}
 * 
 * @param id {@value E_ID}
 * @return
 */
@Operation(
        summary = GET_SPECIFIC_DESC,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = Environment.class))),
                @ApiResponse(responseCode = NOT_FOUND_CODE, description = NOT_FOUND_DESCRIPTION),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/{id}")
Environment getSpecific(@Parameter(description = E_ID) @PathParam("id") String id);
 

/**
 * {@value GET_CLOSE_RESULTS}
 * 
 * @param id{@value PM_ID}
 * @param pageParams
 * @param filterParams
 * @return
 */
@Operation(
        summary = GET_CLOSE_RESULTS,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(
                                schema = @Schema(implementation = ProductMilestoneCloseResultPage.class))),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/{id}/close-results")
Page<ProductMilestoneCloseResult> getCloseResults(
        @Parameter(description = PM_ID) @PathParam("id") String id,
        @Valid @BeanParam PageParameters pageParams,
        @BeanParam ProductMilestoneCloseParameters filterParams);
 

/**
 * {@value GET_ANNOUNCEMENT_BANNER_DESC}
 * 
 * @return
 */
@Operation(
        summary = GET_ANNOUNCEMENT_BANNER_DESC,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = Banner.class))),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("announcement-banner")
public Banner getAnnouncementBanner();
 

/**
 * {@value GET_DEPENDENCY_GRAPH}
 *
 * @param id {@value B_ID}
 * @return
 */
@Operation(
        summary = GET_DEPENDENCY_GRAPH,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = BuildsGraph.class))),
                @ApiResponse(responseCode = NOT_FOUND_CODE, description = NOT_FOUND_DESCRIPTION),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/{id}/dependency-graph")
Graph<Build> getDependencyGraph(@Parameter(description = B_ID) @PathParam("id") String id);
 

@POST
@Path("/failover")
@Operation(
  summary = "Force the leading Singularity instance to restart and give up leadership"
)
public Response forceFailover(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Context HttpServletRequest requestContext
) {
  authorizationHelper.checkAdminAuthorization(user);
  return maybeProxyToLeader(
    requestContext,
    Response.class,
    null,
    () -> this.runFailover(user)
  );
}
 

@GET
@Path("/assertContentDoesNotContain")
@Produces(MediaType.APPLICATION_JSON)
@Operation(description = "Assert that responses content for all requests found by a given URL pattern don't contain specified value.",
        responses = {@ApiResponse(
                description = "Assertion result",
                content = @Content(
                        mediaType = MediaType.APPLICATION_JSON,
                        schema = @Schema(implementation = AssertionResult.class)))})
public AssertionResult contentDoesNotContain(
        @PathParam(PORT)
        @NotNullConstraint(paramName = PORT)
        @PortWithExistingProxyConstraint
        @Parameter(required = true, in = ParameterIn.PATH, description = DocConstants.PORT_DESCRIPTION) int port,

        @QueryParam(URL_PATTERN)
        @NotBlankConstraint(paramName = URL_PATTERN)
        @PatternConstraint(paramName = URL_PATTERN)
        @Parameter(required = true, description = DocConstants.URL_PATTERN_DESCRIPTION) String urlPattern,

        @QueryParam(CONTENT_TEXT)
        @NotBlankConstraint(paramName = CONTENT_TEXT)
        @Parameter(required = true, description = DocConstants.CONTENT_TEXT_DESCRIPTION) String contentText) {

    return proxyManager.get(port).assertAnyUrlContentDoesNotContain(Pattern.compile(urlPattern), contentText);
}
 

/**
 * {@value GET_ALL_DESC}
 *
 * @param pageParams
 * @return
 */
@Operation(
        summary = GET_ALL_DESC,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = BuildConfigPage.class))),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
Page<BuildConfiguration> getAll(@Valid @BeanParam PageParameters pageParams);
 

@GET
@Path("/group/{requestGroupId}")
@Operation(
  summary = "Get a specific Singularity request group by ID",
  responses = {
    @ApiResponse(
      responseCode = "404",
      description = "The specified request group was not found"
    )
  }
)
public Optional<SingularityRequestGroup> getRequestGroup(
  @Parameter(required = true, description = "The id of the request group") @PathParam(
    "requestGroupId"
  ) String requestGroupId
) {
  return requestGroupManager.getRequestGroup(requestGroupId);
}
 

@GET
@Path("/request/{requestId}/crashloops")
@Operation(summary = "Retrieve a map of all open crash loop details for all requests")
public List<CrashLoopInfo> getCrashLoopsForRequest(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Parameter(
    required = true,
    description = "The Request ID to fetch crash loops for"
  ) @PathParam("requestId") String requestId
) {
  final SingularityRequestWithState requestWithState = fetchRequestWithState(
    requestId,
    user
  );
  authorizationHelper.checkForAuthorization(
    requestWithState.getRequest(),
    user,
    SingularityAuthorizationScope.READ
  );
  return requestManager.getCrashLoopsForRequest(requestId);
}
 

@Produces({ MediaType.APPLICATION_JSON })
@Path("/{name}")
@PUT
@Operation(
    summary = "Update an existing new item",
    description = "Put operation with form parameter",
    responses = {
        @ApiResponse(
            content = @Content(schema = @Schema(implementation = Item.class)),
            responseCode = "200"
        )
    }
)
public Item updateItem(
        @Parameter(required = true) @PathParam("name") String name,
        @Parameter(required = true) @FormParam("value") String value) {
    Item item = new Item(name, value);
    items.put(name,  item);
    return item;
}
 

/**
 * {@value GET_BUILDS}
 * 
 * @param id {@value U_ID}
 * @param pageParameters
 * @param buildsFilter
 * @return
 */
@Operation(
        summary = GET_BUILDS,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = BuildPage.class))),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/{id}/builds")
Page<Build> getBuilds(
        @Parameter(description = U_ID) @PathParam("id") String id,
        @Valid @BeanParam PageParameters pageParameters,
        @BeanParam BuildsFilterParameters buildsFilter);
 

/**
 * {@value GET_SPECIFIC_DESC}
 * 
 * @param id {@value P_ID}
 * @return
 */
@Operation(
        summary = GET_SPECIFIC_DESC,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = Product.class))),
                @ApiResponse(responseCode = NOT_FOUND_CODE, description = NOT_FOUND_DESCRIPTION),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/{id}")
@Consumes(MediaType.APPLICATION_JSON_PATCH_JSON) // workaround for PATCH support
Product getSpecific(@Parameter(description = P_ID) @PathParam("id") String id);
 

/**
 * {@value GET_GROUP_CONFIGS}
 * 
 * @param id {@value PV_ID}
 * @param pageParameters
 * @return
 */
@Operation(
        summary = GET_GROUP_CONFIGS,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = GroupConfigPage.class))),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/{id}/group-configs")
Page<GroupConfiguration> getGroupConfigs(
        @Parameter(description = PV_ID) @PathParam("id") String id,
        @Valid @BeanParam PageParameters pageParameters);
 

/**
 * {@value UPDATE_DESC}
 * 
 * @param id {@value P_ID}
 * @param project
 */
@Operation(
        summary = UPDATE_DESC,
        responses = { @ApiResponse(responseCode = ENTITY_UPDATED_CODE, description = ENTITY_UPDATED_DESCRIPTION),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = CONFLICTED_CODE,
                        description = CONFLICTED_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@PUT
@Path("/{id}")
void update(@Parameter(description = P_ID) @PathParam("id") String id, @NotNull Project project);
 

/**
 * {@value PATCH_SPECIFIC_DESC}
 * 
 * @param id {@value P_ID}
 * @param product
 * @return
 */
@Operation(
        summary = PATCH_SPECIFIC_DESC,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = Product.class))),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(responseCode = NOT_FOUND_CODE, description = NOT_FOUND_DESCRIPTION),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@PATCH
@Path("/{id}")
@Consumes(MediaType.APPLICATION_JSON_PATCH_JSON)
Product patchSpecific(@Parameter(description = P_ID) @PathParam("id") String id, @NotNull Product product);
 

/**
 * {@value GET_SPECIFIC_DESC}
 * 
 * @param id {@value PR_ID}
 * @return
 */
@Operation(
        summary = GET_SPECIFIC_DESC,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ProductRelease.class))),
                @ApiResponse(responseCode = NOT_FOUND_CODE, description = NOT_FOUND_DESCRIPTION),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/{id}")
@Consumes(MediaType.APPLICATION_JSON_PATCH_JSON) // workaround for PATCH support
ProductRelease getSpecific(@Parameter(description = PR_ID) @PathParam("id") String id);
 

@POST
@Path("/update")
@Operation(
  summary = "Update the target active instance count for a pending deploy",
  responses = {
    @ApiResponse(
      responseCode = "400",
      description = "Deploy is not in the pending state pending or is not not present"
    )
  }
)
public SingularityRequestParent updatePendingDeploy(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Context HttpServletRequest requestContext,
  @RequestBody(required = true) SingularityUpdatePendingDeployRequest updateRequest
) {
  return maybeProxyToLeader(
    requestContext,
    SingularityRequestParent.class,
    updateRequest,
    () -> updatePendingDeploy(user, updateRequest)
  );
}
 

/**
 * {@value GET_SLC_ENTITIES_STATS_DESC}
 * 
 * @return
 */
@Operation(
        summary = GET_SLC_ENTITIES_STATS_DESC,
        responses = {
                @ApiResponse(
                        responseCode = SUCCESS_CODE,
                        description = SUCCESS_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = Response.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@GET
@Path("/entity-statistics")
public Response getSecondLevelCacheEntitiesStats();
 

@GET
@PropertyFiltering
@Path("/active/states")
@Operation(summary = "Retrieve the list of active task ids for all requests")
public Map<SingularityTaskId, List<SingularityTaskHistoryUpdate>> getActiveTaskStates(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Parameter(
    description = "Use the cached version of this data to limit expensive api calls"
  ) @QueryParam("useWebCache") Boolean useWebCache
) {
  List<SingularityTaskId> activeTaskIds = authorizationHelper.filterByAuthorizedRequests(
    user,
    taskManager.getActiveTaskIds(),
    SingularityTransformHelpers.TASK_ID_TO_REQUEST_ID,
    SingularityAuthorizationScope.READ
  );
  return taskManager.getTaskHistoryUpdates(activeTaskIds);
}
 

@Produces({ MediaType.APPLICATION_JSON })
@Path("/{name}")
@GET
@Operation(
    summary = "Get item by name",
    description = "Get operation with type and headers",
    responses = {
        @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();
}
 

@POST
@Path("/stop")
@Operation(
  summary = "Stop the Mesos scheduler subscriber",
  responses = {
    @ApiResponse(
      responseCode = "403",
      description = "Test resource calls are currently not enabled, set `allowTestResourceCalls` to `true` in config yaml to enable"
    )
  }
)
public void stop() throws Exception {
  checkForbidden(
    configuration.isAllowTestResourceCalls(),
    "Test resource calls are disabled (set isAllowTestResourceCalls to true in configuration)"
  );

  managed.stop();
}
 

@DELETE
@Path("/request/{requestId}/skip-healthchecks")
@Operation(
  summary = "Delete/cancel the expiring skipHealthchecks. This makes the skipHealthchecks request permanent",
  responses = {
    @ApiResponse(
      responseCode = "404",
      description = "No Request or expiring skipHealthchecks request for that ID"
    )
  }
)
public SingularityRequestParent deleteExpiringSkipHealthchecks(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Parameter(required = true, description = "The Request ID") @PathParam(
    "requestId"
  ) String requestId
) {
  return deleteExpiringObject(
    SingularityExpiringSkipHealthchecks.class,
    requestId,
    user
  );
}
 

@POST
@Path("/disabled-actions/{action}")
@Operation(summary = "Disable a specific action")
public void disableAction(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Parameter(required = true, description = "The action to disable") @PathParam(
    "action"
  ) SingularityAction action,
  @RequestBody(
    description = "Notes related to a particular disabled action"
  ) SingularityDisabledActionRequest disabledActionRequest
) {
  final Optional<SingularityDisabledActionRequest> maybeRequest = Optional.ofNullable(
    disabledActionRequest
  );
  authorizationHelper.checkAdminAuthorization(user);
  Optional<String> message = maybeRequest.isPresent()
    ? maybeRequest.get().getMessage()
    : Optional.<String>empty();
  disasterManager.disable(action, message, Optional.of(user), false, Optional.empty());
}
 

@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(
    summary = "Send the default greeting",
    tags = {"Greeting"},
    description = "Send a default greeting to the caller",
    responses = {
        @ApiResponse(
            description = "successful operation",
            responseCode = "200",
            content = @Content(
                schema = @Schema(implementation = Greeting.class)
            )
        ),
        @ApiResponse(responseCode = "404", description = "URI not found")
    })
public Response defaultGreeting() {
    return Response.ok(new Greeting(new Date(), String.format(TEMPLATE, "World"))).build();
}
 

/**
 * {@value ADD_DEPENDENCY_DESC}
 *
 * @param id {@value BC_ID}
 * @param dependency {@value DEPENDENCY_ADD_DESC}
 */
@Operation(
        summary = ADD_DEPENDENCY_DESC,
        responses = { @ApiResponse(responseCode = NO_CONTENT_CODE, description = NO_CONTENT_DESCRIPTION),
                @ApiResponse(
                        responseCode = INVALID_CODE,
                        description = INVALID_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
                @ApiResponse(
                        responseCode = SERVER_ERROR_CODE,
                        description = SERVER_ERROR_DESCRIPTION,
                        content = @Content(schema = @Schema(implementation = ErrorResponse.class))) })
@POST
@Path("/{id}/dependencies")
void addDependency(
        @Parameter(description = BC_ID) @PathParam("id") String id,
        @Parameter(description = DEPENDENCY_ADD_DESC) BuildConfigurationRef dependency);
 

@GET
@Path("/{namespace}/{set}")
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "Get entries from a set")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200",
                 description = "Provides entry names and weights matching query parameters as properties in a json",
                 content = @Content(schema = @Schema(implementation = Map.class))),
    @ApiResponse(responseCode = "400", description = "One of the query parameters has a bad value"),
    @ApiResponse(responseCode = "500", description = serverErrorMessage)
})
public Response get(@Parameter(description = "Namespace identifier") @PathParam("namespace") final String namespace,
                    @Parameter(description = "Name of the set") @PathParam("set") final String set,
                    @BeanParam final SetsDataSourceBean bean) throws IOException {
    logger.info("received request for values in set/namespace {}/{}", set, namespace);
    logger.debug("request parameters: {}", bean);
    final Map<String, Long> entries = this.cantor.sets().get(
            namespace,
            set,
            bean.getMin(),
            bean.getMax(),
            bean.getStart(),
            bean.getCount(),
            bean.isAscending());
    return Response.ok(parser.toJson(entries)).build();
}
 

@POST
@Consumes({ MediaType.APPLICATION_JSON })
@Operation(
  summary = "Create or update a Singularity Request",
  responses = {
    @ApiResponse(responseCode = "400", description = "Request object is invalid"),
    @ApiResponse(
      responseCode = "409",
      description = "Request object is being cleaned. Try again shortly"
    )
  }
)
public SingularityRequestParent postRequest(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Context HttpServletRequest requestContext,
  @RequestBody(
    required = true,
    description = "The Singularity request to create or update"
  ) SingularityRequest request
) {
  return maybeProxyToLeader(
    requestContext,
    SingularityRequestParent.class,
    request,
    () -> postRequest(request, user)
  );
}
 

@POST
@Path("/settings")
@Operation(summary = "Update the settings for the current authenticated user")
public void setUserSettings(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @RequestBody(
    required = true,
    description = "The new settings to be saved for the currently authenticated user"
  ) SingularityUserSettings settings
) {
  userManager.updateUserSettings(user.getId(), settings);
}
 

@POST
@Path("/request/{requestId}/bounce")
@Operation(summary = "Trigger a bounce for a request")
@SuppressFBWarnings("NP_NULL_PARAM_DEREF_ALL_TARGETS_DANGEROUS")
public SingularityRequestParent bounce(
  @Parameter(hidden = true) @Auth SingularityUser user,
  @Parameter(required = true, description = "The request to bounce") @PathParam(
    "requestId"
  ) String requestId,
  @Context HttpServletRequest requestContext
) {
  return bounce(user, requestId, requestContext, null);
}
 

@Operation(summary = "Place an order for a pet", tags = { "store" })
@ApiResponses(value = {
		@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Order.class))),
		@ApiResponse(responseCode = "400", description = "Invalid Order") })
@PostMapping(value = "/store/order", produces = { "application/xml", "application/json" }, consumes = {
		"application/json" })
@ResponseBody
default ResponseEntity<Order> placeOrder(
		@Parameter(description = "order placed for purchasing the pet", required = true) @Valid @RequestBody Order order) {
	return getDelegate().placeOrder(order);
}