OpenAPI UI (a.k.a. Swagger)

Overview

This tutorial shows how to use the OpenAPI UI (a.k.a. Swagger UI) to:

• create a JWT token for authorization
• create a document
• list views
• view Domino REST API databases

The Swagger UI is an OpenSource component supported and maintained by SmartBear and packaged into a WebJar to render the collection of definitions that constitute the Domino REST API. For an introduction, see Swagger UI.

URLs in this tutorial

The URLs in this tutorial point to a local instance of the Domino REST API. When you want to follow it on your own remote server, you need to replace http://localhost with your server address.

Before you begin

• You have already 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.

Create a JWT token for authorization

You need to create a JWT token 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. Go to Swagger UI.

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

   

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

   

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

   

   When your credentials are valid, the returned JSON has the JWT token in the bearer key.

   

5. Copy the JWT token in the bearer key.

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

   

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

   

8. Close the Available authorizations dialog.

Create a document with Swagger UI

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

   

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"
   }
   

   

4. Observe what happens when you supply less fields.

List views with Swagger UI

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.

   

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

   

View specific Domino REST API database

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

   

2. Review the endpoints.

   1. Expand data, authentication, or code.

      

   2. Review the endpoints.

      The admin and design APIs aren't included since they're not appropriate for accessing the demo database's data. The dataSource parameter is always "demo" because the OpenAPI specification is for that Domino REST API database.

      

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 dql.

   

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.