| --- |
| 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/). |
| |
| |