Viewing REST API by using the Swagger user interface

You can access the Swagger user interface to view and test any RESTful APIs that are annotated with the supported annotations.

Important:
  • For security reasons, Swagger should not be exposed in your live production environment.

    You can restrict it from being exposed in the following ways:

    • If the REST API ports are not required to be exposed externally, ensure that they are blocked by your firewall rules. These ports include 8006, and 3738.
    • If you need to expose these ports:
      1. Disable the REST Discovery API for the WebSphere Commerce Server. For more information, see Enabling and disabling the REST Discovery API.
      2. Ensure that you configure your web server to block access to the following swagger endpoints:
        • https://hostname:3738/search/resources/swagger
  • The Swagger UI is provided to you as-is. It contains the WebSphere Commerce REST API and other information that is related to the Swagger backend. Customizing the Swagger UI, for example, to display custom resource handlers, annotations, or extra data is not supported.

Procedure

  1. Start the WebSphere Commerce test server.
  2. Log in to your starter store as a Site Administrator.
    Note: Logging in to the store sets up the security tokens so that you can make REST calls from Swagger. Although you can still view the REST resources in Swagger, failing to log in to the store with the appropriate permissions prevents you from running any REST calls from Swagger.
  3. Access the Swagger UI by using a web browser.
    1. Open a web browser and go to one of the following URL:
      https://localhost/webapp/wcs/stores/servlet/swagger/index.html
    2. In the Explore field, enter one of the following URL, depending on which set of REST API you want to explore.
      • For the WebSphere Commerce REST API: https://WC_hostname:8006/wcs/resources/api
      • For the Search REST API: https://WC_hostname:3738/search/resources/api
      Notes:
      • By default, the Swagger UI web page loads the URL for the WebSphere Commerce REST APIs. After you update the Explore field, click the Explore button to avoid triggering a page refresh.
      • When you test your REST calls by using Swagger, select the storeId that corresponds to the store that you logged in to in Step 2.
      • When you access the Swagger UI page, the same protocol (HTTPS) must be used for the REST API URL in the Explore field, or you will run into cross-origin resource sharing (CORS) errors.