using_swagger.html.md.erb

---
title:  Using the Swagger UI to Browse REST APIs
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

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

Swagger application JARs are included in the Geode 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 Geode Developer REST API-enabled server and JMX Manager as described in [Setup and Configuration](setup_config.html#topic_e21_qc5_m4). For example:

    ``` pre
    gfsh>start server --name=server1  --J=-Dgemfire.start-dev-rest-api=true \
    --J=-Dgemfire.http-service-bind-address=localhost \
    --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true
    ```

    If desired, you can specify a different HTTP port for the developer REST service. For example, `-J=-Dgemfire.http-service-port=8080`. If you do not specify this property, the service is available at the default port 7070.

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

    ``` pre
    http://localhost:7070/gemfire-api/docs/index.html
    ```

    The following Web page appears: <img src="../images/swagger_home.png" id="concept_rlr_y3c_54__image_m15_qcm_x4" class="image" />

3.  In gfsh, connect to the server running the JMX Manager.

    ``` pre
    gfsh>connect --jmx-manager=localhost[1099]
    ```

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

    ``` pre
    gfsh>create region --name=region1 --type=REPLICATE --key-constraint=java.lang.String
    Member  | Status
    ------- | ------------------------------------------
    server1 | Region "/region1" created on "server1"
    ```

5.  In Swagger, click on **region : region** to list all the available endpoints for accessing regions.
6.  In the list of **region** endpoints, click on the **GET /v1** endpoint link. The page displays additional request and response information about the API. <img src="../images/swagger_v1.png" id="concept_rlr_y3c_54__image_kx2_2dm_x4" class="image" />
7.  Click the **Try it out!** button. Any regions you added in step 5 are returned in the response body. <img src="../images/swagger_v1_response.png" id="concept_rlr_y3c_54__image_y2p_tdm_x4" class="image" />
8.  Add an entry to the region by expanding the **POST /v1/{region}** endpoint. <img src="../images/swagger_post_region.png" id="concept_rlr_y3c_54__image_sfk_c2m_x4" class="image" />
9.  Click the **Try it out!** button to see the response body and response code. <img src="../images/swagger_post_region_response.png" id="concept_rlr_y3c_54__image_pmx_k2m_x4" class="image" />

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

For more information on Swagger, see [https://helloreverb.com/developers/swagger](https://helloreverb.com/developers/swagger) and the Swagger Specification at [https://github.com/wordnik/swagger-spec/](https://github.com/wordnik/swagger-spec/).