Using the Swagger UI to Browse REST APIs

VMware Tanzu GemFire Developer REST APIs are integrated with the Swagger™ framework. This framework provides a browser-based test client that allows you to visualize and try Tanzu GemFire REST APIs.

Swagger application JARs are included in the GemFire REST application WAR. You do not need to install any additional libraries to use Swagger.

The following example demonstrates how to access the Swagger UI to browse the APIs.

1. Start a Tanzu GemFire Locator and a Developer REST API-enabled server as described in Setup and Configuration. Specify an http-service-port for the developer REST service, as the default port, 7070, is already taken by the locator. For example:

   gfsh>start locator --name=locator1
   Starting a GemFire Locator in /Users/admin/gemfire-1.2.0/locator1...
   ....
   gfsh>start server --name=server1  --start-rest-api=true \
   --http-service-bind-address=localhost --J=-Dgemfire.http-service-port=8080
   

2. To access Swagger, open a browser and enter the following URL. For example:

   http://localhost:8080/gemfire-api/swagger-ui.html
   

   The following Web page appears:

3. Using gfsh, create one or more regions on the REST API server. For example:

   gfsh>create region --name=region1 --type=REPLICATE --key-constraint=java.lang.String
   Member  | Status | Message
   ------- | ------ | --------------------------------------
   server1 | OK     | Region "/region1" created on "server1"
   
   Cluster configuration for group 'cluster' is updated.
   

4. In Swagger, scroll down to region to view the list of all the available endpoints for accessing regions. (Click on region to expand the list of endpoints, if they are not already visible.)

5. In the list of region endpoints, click on the GET /v1 endpoint link. The page displays additional request and response information about the API.
6. Click the Try it out! button, then Execute. Any regions you added in step 3 are returned in the response body.
7. To add an entry to the region, expand the POST /v1/{region} endpoint.
8. Click the Try it out! button and fill in the parameters. This example uses:
   • region name: “region1”
   • key: “1”
   • Request body: a key/value pair specified as a JSON string, {"1" : "one"}.
9. Click Execute to see the response body and response code. The response indicates that the operation succeeded.
10. To view the new key and value, open the GET /v1/{region} endpoint. Click the Try it out! button and fill in the region name (“region1”). Then click Execute to see all keys and values for the region.

You can use the Swagger interface to try out additional GemFire API endpoints and view sample responses.

For more information about Swagger, see the Swagger website and the OpenAPI specification.