Anotaciones de servicio REST

HCL Commerce Los servicios REST y los servicios REST de búsqueda se anotan, de forma que pueda ver y probar las API con Swagger, una interfaz de servicio REST interactiva. La API de descubrimiento REST genera una lista de las API y los recursos REST analizando las anotaciones en un manejador de recursos. Al documentar los manejadores de recursos REST personalizados con los mismos estándares de anotación que los servicios REST de HCL Commerce, los servicios REST personalizados se pueden ver y probar con Swagger.

Nota: Este tema es relevante para la especificación Swagger 1.x y no para OpenAPI 3.x. Para utilizar especificaciones Swagger más antiguas generadas a partir de anotaciones, establezca la propiedad OAS3Enabled de wc-component.xml a false.
Para obtener más información sobre cómo añadir especificaciones openAPI 3.x para API de REST nuevas o personalizadas, consulte:

Anotaciones REST disponibles

HCL Commerce Los servicios de REST y los servicios de REST de búsqueda se anotan con una combinación de anotaciones REST y JAX-RS personalizadas disponibles en la implementación de Apache Wink. Puede utilizar estas anotaciones al crear los servicios de REST personalizados. Para obtener más información sobre las anotaciones JAX-RS disponibles, consulte:
Nota: HCL Commerce Los servicios REST y los servicios REST de búsqueda utilizan la especificación de Swagger estándar (versión 1.2). Para obtener más información sobre esta especificación de Swagger, consulte Swagger RESTful API Documentation.
En el código siguiente se ilustra un método POST que se ha anotado con una combinación anotaciones REST de HCL Commerce soportadas: 
@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;

}
Con las anotaciones REST soportadas en su lugar, la API de descubrimiento RES genera listas de recursos REST y declaraciones de API que se utiliza Swagger para presentar la API RESTful en forma de documentación interactiva. Cuando vea esta documentación, podrá descubrir los recursos y métodos REST disponibles, y probar la API desde la interfaz de usuario de Swagger.

La interfaz de usuario de Swagger

La interfaz de Swagger se compone de HTML estático, CSS y JavaScript, y se accede a ella a través del navegador web. La infraestructura de Swagger consulta la API de descubrimiento RES para visualizar los manejadores de recursos REST en orden alfabético. En la captura de pantalla siguiente se muestra la interfaz de Swagger, concretamente el manejador de recursos de ejemplo que se ha anotado con anterioridad:
Captura de pantalla de la interfaz de usuario de Swagger
Donde
  • Cada clase de manejador de recursos tiene una breve descripción del servicio.
  • Mostrar/ocultar expande o contrae el contenido de la API de cada clase.
  • Listar operaciones muestra una vista resumida del contenido de la API, donde se visualiza una fila para cada vía de acceso de método, con una breve descripción del servicio.
  • Expandir operaciones muestra una vista ampliada del contenido de la API, donde las filas se visualizan para la clase de respuesta, los parámetros y códigos de estado de cada método. La API se puede probar dinámicamente, seleccionando ¡Probar ahora! en la vista ampliada.
  • Sin formato muestra la información sin formato que la interfaz de usuario de Swagger utiliza para rellenar la página.