Note: this example points towards an API targeting a test database with test data.
Provided with the API is Swagger UI API documentation. This document describes all available functions, along with examples and descriptions for arguments and return values. It also lets you try out the functions directly from your browser.
To access the documentation for the test site, navigate to this address: https://testapi.diap.online (Live site is: https://api.diap.online).
You are presented with a list of all the functions the API exposes.
The first function is to try the login function. All functions except that, require the caller being authorized through a JWT Bearer token. The login function will provide that token. You can read more about how authorization works here.
Click the "POST /api/Account/Login" button to reveal a panel documenting the function.
This documents how to call the function. You can read the request URL, method, content-type and see an example of the request and response body. In this case, it is:
Request URL: https://sfc-diap-test-api.westeurope.cloudapp.azure.com/api/account/login
Request Method: POST
Header:
Content-Type: "application/json"
Body:
{
"username": "string",
"password": "string"
}
The page also displays the various responses available. E.g. a successful response, HTTP Code 200, will contain a string, which is the Bearer token.
Any time data is provided, in either the request or in the response, an example of the data model is generated. To view documentation for the specific model, click on the "Model" text next to "Example Value". This will hide the example, and display the documentation for the model. For the login credentials model, it will look like this:
This lets you see the format of the expected body, a description for each property, whether it is required and what data type is expected.
All models used in the API are listed in the bottom of the Swagger UI page:
One can call the method straight from the website by pressing the "Try it out" button. This lets you edit the example, where you can enter your credentials and press execute to receive a Bearer token.
Press Execute. The exact request and response is displayed. If the body was not malformed, and the credentials were correct, a JWT bearer token is returned in the response body:
This token must be used to authorize calls to any other functions. To do this, first copy the token with the quotation marks. Then press the "Authorize" button in the top. Enter "Bearer <token>" in the input field:
Press Authorize. Subsequent calls are now correctly authorized for as long as the JWT Bearer token is valid. We can test whether it works by simply calling the list units function. It does not take any parameters, so we can directly execute it. Do this by pressing the "Try it out" button and then "Execute".
If it succeeded, we should see an HTTP Code 200/OK reply from the server, with a list of units in the body:
If the token is incorrect or expired, the server will return a HTTP Code 401/Unauthorized:
This covers how to use Swagger UI to discover and test the API. As the Swagger UI page is generated directly from API code, it is always exact and up-to-date.