Working with Swagger UI

In the base configuration, each InsuranceSuite application contains a static distribution of the Swagger UI tool. You can use this tool to browse API documentation live from the same server that is publishing the APIs. The Swagger UI tool is available from the following location:
  • servletBasePath/resources/swagger-ui/
On the local server, the location Swagger UI becomes the following URL:
  • http://localhost:8180/pc/resources/swagger-ui
In this URL, the servletBasePath variable becomes:
  • localhost:8180/pc/

Swagger UI performance

Swagger UI can be quite slow. As a consequence, Guidewire does not recommend that you use Swagger UI to test large APIs. For the most part, use Swagger UI to view schema information about an API only. Guidewire recommends that you use a third-party tool such as Postman to design, develop, and test REST APIs instead.

The Swagger UI screen

The Swagger UI screen contains the following elements.
The Explore entry field
At the top of the Swagger UI entry screen is a box in which you can enter the URL of a specific REST API. Clicking the Explore button returns the list of endpoints and HTTP operations for the that specific API. To determine the API URL, review the list of published APIs generated by the /apis endpoint.
The base URL link
Directly underneath the API name (in large font), the screen defines the base path for this particular API, as well as a clickable link to the Swagger schema for the API. You can also see the same information in a more human-readable form lower down on the Swagger UI screen.
The Authorize dialog
If authentication is set up correctly, Swagger UI displays an Authorize button near the top of the screen in which you can enter your user credentials. This enables the Swagger UI to authorize your API requests. If basic authentication is not set up, you can still browse the documentation using Swagger UI. However, you cannot try live requests, as Swagger UI cannot authenticate those requests correctly.
HTTP operations
The lower portion of the Swagger UI screen contains a list of the valid HTTP operations for the listed API, organized by API endpoint. Clicking one of the API operation buttons expands a pane that provides further information about this particular operation, including the following:
  • A description of the operation
  • Any parameters that the operation uses
  • Information about the operation parameters such as a description, whether it is required, and the parameter type
  • Response code associated with the request
You can also try out the action of a particular API operation by clicking Try it out. If you need to enter specific data for a parameter, use the fields that open to do so.

More information

For information on Swagger UI, refer to the following web site: