Skip to main content
Version: 10.9.x

Documentation Portal

Documentation is a vital part of any Restful API in order to drive consistency and discipline across your API development workflow.

The documentation Portal section in the Developer Console area exposes the Open API documentation of all services and CRUDs that you have defined and exposed. In this way, you will be able to obtain information about the routes exposed by your resources from a single section and to test the correct functioning of each of them.

note

API Portal service is responsible for the generation of the Documentation Portal section of the Console. To learn more about this plugin and how to use it to expose your Open API documentation, visit this link

You can share API documentation within your company, externally to partners and suppliers.

In order to test each API, you can access your tags on the right side of the screen, where the APIs are grouped according to their tags: by clicking on one tag, you will visualize all the APIs that belong to that tag.

For example, if you have created a CRUD with the "Plates" tag, you will be able to select it:

Tag Selection

The Console will show you a request example for each request type that you can use to easily test your Api. You just need to copy the request example, paste it in the Json editor and you will be ready to test your Api!

note

The available documentation is generated by Swagger Aggregator.
You can apply custom configurations directly from the Console

tip

If you want to hide some endpoints of your API from the API Portal documentation you can do this in the Management section of the endpoint you want to hide.

In the following section you will see how to interact with the Documentation Portal graphical interface and how to test your exposed routes by sending requests to them.

CRUD Documentation

After having exposed and released a CRUD you can find the relative APIs documentation in the API Portal.
APIs are exposed automatically by the CRUD Service, check out the CRUD Endpoints section to know all details of endpoints and how to perform CRUD operations.
Below you can find some basic examples of CRUD operations you can do with API Portal.

GET request

How to "Get a list of plates"

If you want to test the GET endpoint, you need to click the row that will expand it.

In the Query Params section, you can filter and sort all the request configuration you need by ticking the boxes of the information you are looking for. For instance, we ticked id, name, description, and price. So, only these specific contents will be passed upon the GET request.

Query parameters

You can hide the visibility of the content of an entire section by pushing the button Collapse.

Collapse button

Then you can expand it again by clicking Expand

By opening the Object Properties you can hide the properties that you don't want to retrieve just by unchecking the boxes. As you can see below, we uncheck creatorId and type, as they don't appear in the list.

Object Properties

Now you have the ability to test the API request by pushing Try it - if the APIs are protected, you need to authenticate yourself by filling the Secret in, as shown below.

Secret Authentication

Once the single API is selected, in this area you can see the structure of the API and the data that are exposed.

Below you can see the screenshot of a successfull request to our running API, we can see 200 as OK success status response code and in the black box on the right, you can see the request, that can be seen as a cURL,in Node, in JavaScript, and in Java. In the second box, you can see the response of the body with the list of the plates.

You can see all the Parameters Type: query, path, header, and body.

GET Request

In addition, you can also edit it in JSON as shown below.

Json Editor

POST request

How to "Add a new item to the plates collection"

In order to test the POST endpoint, you need to click the row that will open it up. Now you have the ability to test the API request by entering the information that you need. In our case we added a plate of "onion rings" with its description and its price. Then push Try it - if the APIs are protected, you need to authenticate yourself by filling the Secret in.

Below you can see the screenshot of a successfull request to our running API, we can see 200 as OK success status response code, a new ID was created and in the black box on the right, you can see the request, that can be seen as a cURL,in Node, in JavaScript, and in Java.

Post Request

Visibility. Always remember the status, whether it is private, public, trash or deleted.

Otherwise, you can add a new item to the collection by directly writing the information you need in the Json Schema by clicking the Edit Json button.

In our example, we successfully added the plate Lasagna, as we can see 200 as OK success status response code. Remember to tick all the boxes of the body params you want to add. In the example, you can see in the Json Schema we ticked "name" in the body params.

Post Request of Lasagna dish

You can also see the complete Json Schema and all the type variables both for the request and response.

Json Schema

DELETE request

How to "Delete a plate from the plates collection"

If you want to test the DELETE endpoint, you need to click the row that will open it up. Now you have the ability to test the API request by putting the ID of the plate that you want to delete and then pushing Try it - if the APIs are protected, you need to authenticate yourself by filling the Secret in.

Below you can see the screenshot of a successfull request to our running API. You can see 204 as No content status response code and in the black box on the right, you can see the request, that can be seen as a cURL,in Node, in JavaScript, and in Java.

Delete Request

By opening the Object Properties you can hide the properties that you don't want to delete just by unchecking the boxes.

For instance, we uncheck all the properties that we want to keep. You can also look for a property in the search box and then push add

Hide Properties

Visibility. Always remember the status, whether it is private, public, trash or deleted.

PATCH request

How to "Update a plate of the collection by ID"

In order to test the Patch endpoint, you need to click the row that will open it up. Now you have the ability to test the API request by editing the fields you want.

In our case, we want to edit the name of a plate from "Salmon" to "Salmon with veggie". We retrieved the correct ID from the GET request and we entered it in the "path params". Since we want to change the name of the plate, we will tick the operator $set and name, and we will type the new name: Salmon with veggie.

Then, push Try it - if the APIs are protected, you need to authenticate yourself by filling the Secret in.

Below you can see the screenshot of a successfull request to our running API, we can see 200 as OK success status response code with the new name. In the black box on the right, you can see the request, that can be seen as a cURL,in Node, in JavaScript, and in Java.

Patch Request

Field Update Operators

In the following table you can find the modifiers of the Body Params:

NameDescription
$setSets the value of a field in a document
$unsetRemoves the specified field from a document
$incIncrements the value of the field by the specified amount
$mulMultiplies the value of the field by the specified amount
$currentDateSets the value of a field to current date, either as a Date or a Timestamp
$pushAppends a specified value to an array
info

By opening the Object Properties you can hide the properties that you don't want to edit just by unchecking the boxes.

tip

Always remember the status, whether it is private, public, trash or deleted.