Exploring REST API using Swagger UI

What is Swagger UI?

Swagger UI is an open-source tool that enables you to visualize and interact with RESTful web services which are documented using the OpenAPI 3.0 specification. It provides a user-friendly interface for you to explore and try out the APIs.

Accessing Swagger UI

To access Swagger UI, navigate to the following URL:

https://{SERVER_URL}/api/swagger-ui/index.html

Replace {SERVER_URL} with the actual domain name where the application is deployed.

For example:

If the application is deployed on primavera.oraclecloud.com, the Swagger UI URL would be: https://primavera.oraclecloud.com/api/swagger-ui/index.html.

Exploring Endpoints

To explore endpoints in Swagger UI:

  1. Browse Tags: Browse the list of available tags on the left-hand side of the page. Each tag represents a group of related endpoints.
  2. Expand Tag: Click on a tag to expand it and view the list of endpoints within that tag.
  3. View Endpoint Details: Click on an endpoint to view its details, including:
    • Request Body Schema: View the OpenAPI schema definition for the request body.
    • Example Value: Click on the "Example Value" tab to view examples of valid request bodies.
    • Response Body Schema: View the OpenAPI schema definition for the response body.
  4. Invoke Endpoint: Once you have reviewed the endpoint details, you can invoke the endpoint by clicking the "Try it out" button.

Trying it Out

To try out an endpoint in Swagger UI:

  1. Setting the Authorization: To try out this API, you must first configure the required authorization headers. Click Authorize and enter the necessary header values. For instructions on generating these values, refer to the "Setting Authorization" section below.
  2. Click "Try it out": Click Try it out next to the endpoint.
  3. Auto-Populated Request Body: The request body text box will be auto-populated with existing example data. You can select any of the available examples and use it directly or customize it as per your requirements.
  4. Customize Request Body: Modify the request body as needed to suit your testing requirements.
  5. Execute: Click Execute to send the request.
  6. View Response: View the response from the server, including status code, headers, and body content.

Setting Authorization

To set authorization in Swagger UI, follow these steps:

  1. Obtain OAuth Token: Generate an OAuth token using an external REST client tool like REST clients or cURL by referring to the detailed steps in How Does Primavera Cloud Support OAuth 2.0?
  2. Extract Required Values: From the OAuth token response, extract the following values:
    • access_token (OAuth token)
    • requestHeaders.primeTenantCode
    • requestHeaders.x-prime-identity-app
    • requestHeaders.x-prime-region
  3. Setting OAuth Token and other Headers in Swagger UI:
    1. On the Swagger UI page, click Authorize.
    2. In the Available authorizations dialog box, enter the corresponding extracted value and click the Authorize button below the value input field for each field.
      • bearerAuth: Enter the extracted access_token value.
      • primeTenantCode: enter the extracted requestHeaders.primeTenantCode value.
      • x-prime-identity-app: Enter the extracted requestHeaders.x-prime-identity-app value.
      • x-prime-region: Enter the extracted requestHeaders.x-prime-region value.
    3. After all values are entered and authorized, click any of the Close buttons to close the dialog box.
  4. Verification: To verify that authorization has been configured correctly in Swagger UI, invoke the Test API Connection endpoint located under the Util tag in Swagger UI. A successful response will return a 200 OK status code, and the response body will contain the message "Connection Successful", indicating that the authorization headers have been properly set up and authenticated successfully.

Note

  • To view all the request and response body schemas along with their properties, expand the Schemas section on the Swagger UI page located at the end of the page after all the tags. This section is expandable, enabling you to view the schema details as needed.
  • Before trying out the features in Swagger UI, review all the topics in the Get Started section of this document to learn about the supported features in the Primavera Cloud API.