REST service annotations

HCL Commerce REST services and Search REST services are annotated so you view and test the APIs with Swagger, an interactive REST service interface. The REST Discovery API generates a list of REST resources and APIs by parsing annotations on a resource handler. By documenting your custom REST resource handlers with the same annotation standards as HCL Commerce REST services, your custom REST services can be viewed and tested with Swagger.

Note: This topic is relevant to the Swagger 1.x specification, and not to OpenAPI 3.x. To use older Swagger specifications generated from annotations, set the OAS3Enabled property in wc-component.xml to false.
For more information on adding openAPI 3.x specifications for new or custom REST APIs, see:

Available REST annotations

HCL Commerce REST service and Search REST services are annotated with a combination of custom REST and JAX-RS annotations available from the Apache Wink implementation. You can use these annotations when you are creating your custom REST services. For more information about the available JAX-RS annotations, see:
Note: HCL Commerce REST and Search REST services use the standard Swagger specification (version 1.2). For more information about this Swagger specification, see Swagger RESTful API Documentation
The following code illustrates a POST method that was annotated with a combination of the supported HCL Commerce REST annotations: 
@POST
@Path("catalogEntryUpdate")
@Description("A sample REST POST that executes the CatalogEntryUpdateCmd based on the request parameters and profile specified.")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML, MediaType.APPLICATION_XHTML_XML, MediaType.APPLICATION_ATOM_XML })
@AdditionalParameterList({
    @ParameterDescription(name = ParameterDescription.BODY_NAME, paramType = ParameterDescription.BODY_TYPE, 
     description = "CatalogEntryUpdate request body.", typeClass = CatalogEntryUpdateRequest.class)
})
@ResponseSchema(valueClass = CatalogEntryUpdateResponse.class, responseCodes = {
    @ResponseCode(code = 200, reason = RESPONSE_200_DESCRIPTION),
    @ResponseCode(code = 400, reason = RESPONSE_400_DESCRIPTION),
    @ResponseCode(code = 401, reason = RESPONSE_401_DESCRIPTION),
    @ResponseCode(code = 403, reason = RESPONSE_403_DESCRIPTION),
    @ResponseCode(code = 500, reason = RESPONSE_500_DESCRIPTION)
})
public Response processRequest(
      @PathParam("storeId") @ParameterDescription(description = PARAMETER_STORE_ID_DESCRIPTION, 
       valueProviderClass = StoreIdProvider.class, required = true) String storeId,
      @QueryParam(value = "responseFormat") @ParameterDescription(description = PARAMETER_RESPONSE_FORMAT_DESCRIPTION, 
       valueProviderClass = ResponseType.class) String responseFormat,
      @QueryParam(value = "profileName") @ParameterDescription(description = PARAMETER_PROFILE_NAME_DESCRIPTION) String profileName)
{

    Response result = executeConfigBasedCommandWithContext(CatalogEntryUpdateCmd.class.getName(), profileName, responseFormat,
        storeId, null);

    return result;

}
With the supported REST annotations in place, the REST Discovery API generates resource listings and API declarations that are used by Swagger to present the RESTful API in the form of interactive documentation. When you are viewing this documentation, you can discover the available REST resources and methods, and test the API from inside the Swagger interface.

The Swagger user interface

The Swagger interface is composed of static HTML, CSS, and JavaScript, and it is accessed through your web browser. The Swagger framework queries the REST Discovery API to display your REST resource handlers in alphabetical order. The following screen capture shows the Swagger interface, specifically the sample resource handler that was annotated earlier:
Swagger UI screen capture
Where
  • Each resource handler class has a short description of the service.
  • Show/Hide expands or collapses the API content of each class.
  • List Operations displays a summarized view of the API content, where a row is displayed for each method's path, with a short description of the service.
  • Expand Operations displays an expanded view of the API content, where rows are displayed for each method's response class, parameters, and status codes. The API can be dynamically tested by selecting Try it out! in the expanded view.
  • Raw displays the raw information that the Swagger UI uses to populate the page.