Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Using the ArangoDB Swagger.io Interactive API Documentation

DZone's Guide to

Using the ArangoDB Swagger.io Interactive API Documentation

Learn how to work with the Swagger.io API tool and how to work with Swagger.io APIs generated by a Foxx application.

· Database Zone ·
Free Resource

Slow SQL Server? These SentryOne resources share tips and tricks for not only troubleshooting SQL Server performance issues, but also preventing them before they hit your production environment.

ArangoDB can bundle its regular API documentation in Swagger.IO API description format. You can browse and explore it interactively via the ArangoDB web interface.

Working With the Swagger.io API Tool

Now you've loaded the Swagger.io API documentation, let's play with it. We're choosing a route that accepts a simple JSON post document. Executing a simple AQL query does so.

As shown above, we scrolled down to AQL and clicked on POST /_api/query

It already shows a similar documentation, as we could also see on the official HTTP API documentation page.

Now, we scroll down past the ready-made examples to the interactive Swagger example generation:

You can switch the example JSON window to a model window containing the documentation of the respective JSON attributes. This can aid you in composing a sensible JSON acceptable by the server.


When we click on Try it out, the JSON post document becomes editable.

We choose a very simple query, which should introduce no hassle at all (1): RETURN 1, and press (2) Execute:

Swagger will generate an example curl command line (3) and talk to the ArangoDB Server and put the result into the output (4). For this example, it will re-use the JSON Web Token of your current web session. Since we may not necessarily want to use JWT in curl, we will choose HTTP Basic authentification in our shell (for the user root with an empty password):

Since the server would return a not-so-human-readable JSON document, we use the handy JQ tool to beautify and colorize the JSON document so we can better comprehend it.

Working With Swagger.io APIs Generated by Foxx

Foxx autogenerates a Swagger API definition for you. To browse that autogenerated documentation, we will install one of the sample apps provided (Itzpapalotl):

We click on the service to get to its overview page:


Clicking on API will open the swagger interface to our itzpapalotl instance:

We choose the /random route, and may execute it similar to how we previously did with the query interface:


We can see again that the JWT is passed along. Since the routes of a Foxx app don't necessarily need the authentification of the host, we may also invoke the /random route without the token:


Database monitoring tools letting you down? See how SentryOne empowers Enterprises to go faster.

Topics:
api ,swagger ,json ,arangodb ,swagger.io ,database ,tutorial

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}