Annotations de service REST

HCL Commerce Les services REST et services REST de recherche sont annotés afin que vous puissiez visualiser et tester les API avec Swagger, une interface de service REST interactive. L'API Discovery REST génère une liste de ressources REST et d'API en analysant les annotations sur un gestionnaire de ressources. En documentant vos gestionnaires de ressources REST personnalisés avec les mêmes normes d'annotation que les services REST HCL Commerce, vos services REST personnalisés peuvent être consultés et testés avec Swagger.

Remarque : Cette rubrique est pertinente pour la spécification Swagger 1.x et non pour OpenAPI 3.x. Pour utiliser des spécifications Swagger plus anciennes générées à partir d'annotations, définissez la propriété OAS3Enabled dans wc-component.xml sur false.

Pour plus d'informations sur l'ajout de spécifications openAPI 3.x pour des API REST nouvelles ou personnalisées, voir :

Annotations REST disponibles

HCL Commerce Les services REST et services REST de recherche sont annotés avec une combinaison d'annotations personnalisées REST et JAX-RS disponibles à partir de l'implémentation Apache Wink. Vous pouvez utiliser ces annotations lorsque vous créez vos services REST personnalisés. Pour plus d'informations sur les annotations JAX-RS disponibles, voir :

Remarque : HCL Commerce Les services REST et les services REST de recherche utilisent la spécification Swagger standard (version 1.2). Pour plus d'informations sur cette spécifications Swagger, voir Swagger RESTful API Documentation

Le code suivant illustre une méthode POST qui a été annotée avec une combinaison des annotations REST HCL Commerce prises en charge :

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

}

Avec les annotations REST prises en charge, l'API Discovery REST génère des listes de ressources et des déclarations API utilisées par Swagger pour présenter l'API RESTful sous forme de documentation interactive. Lorsque vous consultez cette documentation, vous pouvez découvrir les ressources et méthodes REST disponibles et tester l'API depuis l'interface Swagger.

L'interface utilisateur Swagger

L'interface Swagger est composée d'éléments HTML, CSS et JavaScript statiques, et elle est accessible via votre navigateur Web. L'a structure Swagger interroge l'API Discovery REST pour afficher vos gestionnaires de ressources REST dans l'ordre alphabétique. La capture d'écran suivante montre l'interface Swagger, en particulier l'exemple de gestionnaire de ressources qui a été annoté précédemment :
capture d'écran swagger UI

Où

Chaque classe de gestionnaire de ressources dispose d'une courte description du service.
Afficher/Masquer étend ou réduit le contenu de l'API de chaque classe.
Répertorier les opérations affiche une vue récapitulative du contenu de l'API, où une ligne s'affiche pour le chemin d'accès de chaque méthode, avec une courte description du service.
Développer les opérations affiche une vue étendue du contenu de l'API, où les lignes s'affichent pour la classe de réponse, les paramètres et les codes de statut de chaque méthode. L'API peut être testée dynamiquement en sélectionnant Essayez-le ! dans la vue étendue.
Brut affiche les informations brutes que l'interface utilisateur Swagger utilise pour remplir la page.