New features in OpenRouteService Interactive documentation
Mar 6th, 2019 by Amon Santana
The ORS Playground is an interactive API documentation application that allows the users to explore and interact with all the API services. The elements, inputs and forms are built from a swagger documentation file. Since the first release of the new OpenRouteService API Playground in November we have being worked on it to make some important improvements. A good part of the changes may not be easily noticed and some other are engineering changes that will easy the maintenance and the evolution of the application. But there are also important features that boost the user interaction with the API.
Assisted object fillling
What is new?
- Assisted JSON object filling
- Validation and auto-focus on invalid input and auto tab switch
- Limitless nested properties support
- Support map for POIs and MapSurfer endpoints
- Added support for path parameters
- Listing body parameters at form root level and JSON body preview
- Improved abstractions regarding doc parsing and extracting data from response
- Compatible with API/Core v5
- Added support for parameters dependencies
New features
Assisted object filling:
One of the most important features added was the assisted object filling. As the the API requires some parameters with nested objects, initially the user should compose a string representing the JSON object expected by the API. Now, the application identifies this case and offers and assisted filling, open a modal to guide the user through the sub properties filling based also on the API definitions, showing possible values and types. The users still have the option to paste directly a JSON string.
Validation and auto-focus on invalid input/tab:
When a user tries to submit the form the application will indicate if there are invalid fields and will also check this across tabs (body, path, URI and header parameters tabs). If an invalid field is found, the application will auto switch to the tab containing the invalid field, and focus on it. It is important to highlight that the validation and auto switch is done also based on the attributes specified in documentation.
Dependencies:
The second most important feature: this allows dependencies between parameters to be declared on the swagger documentation. Once this is specified in the documentation, the parser will take it into account and will display parameter fields conditionally, based on the value of other declared parameter field. This allows the application to present the form progressively. According the changes made by the user the fields can be shown/hidden. The fields not available are listed in bottom section with a programmatic generated explanation why it is disabled.
Parameter dependencies support
Limitless nested properties:
Improving the Assisted object filling, this feature has extended the initial behaviour, adding the capability of provide assisted object filling for nested para properties recursively.
Added support for new endpoints:
Added support for POIs endpoint, that returns points of interest in the area surrounding a geometry and for MapSurfer endpoint, that provides map tiles in PNG format. To be able to support MapSurfer we had to add the support for path parameters, that change the URL path instead of GET or POST parameters.
Body parameters in root form and JSON preview:
The endpoints of the type POST require a body parameter, that usually must be filled with a JSON object. Now in this case the list of body parameters are rendered at the root level of the form and it comes with a body preview field, that will display the JSON generated based on the user inputs. It also possible directly paste a JSON body to run the request.
POIs and body preview
Internal improvements
- The abstractions regarding the strategies to parse the swagger documentation file were improved. Now it is easier to add more parser versions and API response data extractor versions.
- The application was made compatible with the new 5.0 version of the API/core that is about to be released, reading from auto-generated swagger files.