| --- |
| 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. |
| --> |
| |
| <%=vars.product_name_long%> 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 <%=vars.product_name%> REST APIs. |
| |
| Swagger application JARs are included in the <%=vars.product_name%> 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 <%=vars.product_name%> Locator and a Developer REST API-enabled server as described in [Setup and Configuration](setup_config.html#topic_e21_qc5_m4). |
| Specify an `http-service-port` for the developer REST service, as the default port, 7070, is already taken by the locator. For example: |
| |
| ``` pre |
| gfsh>start locator --name=locator1 |
| Starting a <%=vars.product_name%> Locator in /Users/admin/apache-geode-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: |
| |
| ``` pre |
| http://localhost:8080/geode/swagger-ui.html |
| ``` |
| |
| The following Web page appears: <img src="../images/swagger_home.png" id="concept_rlr_y3c_54__image_m15_qcm_x4" class="image" /> |
| |
| 3. 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" |
| ``` |
| |
| 4. In Swagger, click on **region : region CRUD operations** to list all the available endpoints for accessing regions. |
| <img src="../images/swagger_region_endpoints.png" class="image" /> |
| 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. <img src="../images/swagger_v1.png" id="concept_rlr_y3c_54__image_kx2_2dm_x4" class="image" /> |
| 6. 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" /> |
| 7. 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" /> |
| 8. 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 <%=vars.product_name%> API endpoints and view sample responses. |
| |
| For more information on Swagger, see the [Swagger website](http://swagger.io/) and the [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification). |
| |