Skip to content

Using Swagger UI

Overview

This tutorial guides you through using the Swagger UI to visualize and interact with the Domino REST API endpoints.

The Swagger UI is an open source component supported and maintained by SmartBear and packaged into a WebJar to render the collection of definitions that constitute the Domino REST API. It enables you to visualize and interact with APIs without having any of the actual implementation logic in place. The APIs are automatically generated from the OpenAPI Specification with the visual documentation making it easier to implement the back end code at a later stage.

Before you begin

  • You have created a schema using the Demo.nsf database.
  • You have activated the database forms and views of your created schema.
  • You have created a scope.

For more information, see Using Admin UI.

Video tutorial

You can watch the video for a visual walkthrough of using the Swagger UI. The steps in the video closely follow the instructions in this topic and intend to serve as a visual reference to enhance your understanding. The video shows you the instructions for creating a JWT token for authorization, creating a document, listing views, and working with specific Domino REST API databases.

Authorize with JWT token

You need to create a JWT token and use it to get proper authorization to try out the endpoints. Without proper authorization, you can try executing the endpoints, but you will get an access error.

  1. Open Swagger UI by navigating to http://localhost:8880/openapi/index.html in your browser.

    The URL points to a local instance of the Domino REST API. To access it from your own remote server, replace http://localhost with your server address.

  2. Select your server from the Servers drop-down list.

    JwtToken

  3. Go to and expand authentication, and then expand the POST /auth endpoint.

    JwtToken

  4. In the Request body, replace the username and password values with your Domino REST API username and password, and then click Execute.

    Swagger login

    If your credentials are valid, the response will include a JSON object containing the JWT token in the bearer key.

    Bearer

  5. Copy the JWT token string in the bearer key.

  6. Go to the top of the page and click Authorize.

    JwtToken

  7. In the Available authorizations dialog, paste the copied JWT token in the Value field under jwt (http, Bearer), and then click Authorize.

    JwtToken1

  8. Close the Available authorizations dialog.

Create a document

  1. Go to and expand data, and then go to and expand the POST /document endpoint.

    Data Document

  2. Make sure that the scope name provided for the dataSource parameter is the same as the scope name you created for your schema.

  3. In the Request body, enter all the mandatory field values as shown below, and then click Execute.

    {
 "Form": "Customer",
 "Color": "Red",
 "Pet": "Hamster",
 "email": "me@donotreply.com",
 "first_name": "John",
 "last_name": "Doe"
}

    SwaggerAPI

  4. Observe what happens when you supply less fields.

List views

  1. Go to and expand data, and then go to and expand the GET /lists endpoint.

  2. In the dataSource, enter the scope name, and then click Execute.

    Make sure that the scope name you entered is the same as the scope name you created for your schema.

    SwaggerAPIViews

  3. Check the Server Response to see the information on available views or folders.

    SwaggerAPIViews

Explore specific Domino REST API databases

  1. Select a specific Domino REST API database from the Select a definition drop-down list.

    SwaggerAPIDatabase

    For example purposes, the Domino REST API database demo is going to be selected from the list.

  2. Review the endpoints.

    1. Expand the endpoint categories, such as data, authentication.

      SwaggerAPIDatabase

    2. Review the endpoints.

      The admin and design APIs aren't included since they're not appropriate for accessing the database's data. The value of the dataSource parameter always corresponds to the name of the selected Domino REST API database. Based on the example image, the value of the dataSource parameter is "demo" because the OpenAPI specification is for that Domino REST API database.

      SwaggerAPIDatabase

  3. Review the schemas at the bottom. If you haven't specified read/write fields on a form, you'll see the genericFormResponse/genericFormRequest. If you have specified read or write fields, you'll see a schema for formName-modeName Responses/formName-modeName Requests.

    In the following example image, the read or write fields have been specified so you can see the schema for formName-modeName Responses/formName-modeName Requests. Wherein, the formName is Customer and the modeName is default and odata.

    SwaggerAPIDatabase

You can share the specific Domino REST API database to other developers who also consume the Domino REST API for that database by copying the URL and then sending it to those developers.

Additional information