HCL Commerce Version 9.1.6.0 or later

Maintaining OpenAPI endpoints

To edit an OpenAPI specification, use the Swagger Editor. The Editor is an in-browser, onlinetool with built-in validation tools and other aids for working with Swagger specifications.

Before you begin

To view the Rest APIs with the Swagger interface, use the Swagger Editor. You can set up a local copy of the editor and user interface; for more information see Setting up a local Swagger instance.

Procedure

  1. Open the Swagger JSON file you are planning to update.
    You can either fetch the file, as described in HCL Commerce REST API, or you can access it from one of the HCL Commerce servers:
    • Transaction: WC/xml/config/oas3/transaction
    • Transaction: WC/xml/config/oas3/admin
    • XC: commerceue-app/src/main/resources/com/ibm/commerce/ue/rest
  2. Navigate to the Swagger Editor.
  3. Copy and paste the contents of the Swagger JSON into the Swagger Editor left-hand panel.
  4. Make your changes to the specification.
    Note: You can use the Insert option to add path items, operation, info, external documentation, tag declaration, tags to operation, servers, and example Responses. Validation errors will appear in a notification at the top of the right-hand pane.
  5. When you have completed editing the JSON file, use a JSON validator to ensure its validity. The Swagger Editor does not validate JSON linting support, so parse it through a linter to validate linting.
  6. Copy and paste the validated contents back into your text editor, where you originally opened the file.
    Important: Do not use the File > Save as JSON option in the Swagger Editor. Doing this will create a JSON file that uses two spaces rather than four spaces for tabs. The four-space tab format is required.