API documentation

Opening the documentation in Swagger

The API documentation is automatically generated and can be displayed in Swagger using the API documentation menu in the cluster manager.
It displays all the API methods exposed by your entity views and server methods.
Each API method has a description, a list of available parameters, response codes as well as request and response data examples.

Customizing the documentation

Because the documentation is automatically generated, it can provide incorrect descriptions or non-meaningful examples. You can set custom values in Neos Studio to improve them.

Server methods

When you create a server method, you can define a description. This description is displayed in Swagger next to the corresponding API.
In the Advanced options of a server method, you can set a documentation. The documentation is displayed in Swagger when you unfold the corresponding API.

Note

Only documentation in the main language is displayed in Swagger.

Entity view routes

In the Web API panel of an entity view, you have the possibility to set the documentation for each exposed route.
You can set a description that is displayed in Swagger next to the corresponding API.
You can also set a documentation, it is displayed in Swagger when you unfold the corresponding API.

API request and response examples

Request and response examples can be customized to replace their generic values with values that reflect real world usage.
This can be done either on entity properties or entity view properties in the Example value for API documentation property of the Documentation panel.

Note

Reference and collection properties cannot have an example value.
However, example values from the Related entity view defined on reference and collection properties of an entity view are automatically used in API examples.

Note

A value set on an entity is used for all the API routes of the entity views based on said entity.
A value defined on an entity can be overridden on an entity view.

You can set any value you want as long as they are in a valid JSON format (null, boolean, number, string, array or object).
The set value replaces the corresponding value in Swagger request and response examples.

Note

You do not need to set an example value for each property. Properties without example values use the default autogenerated value.

Here is the list of valid JSON formats for each property type :

• AutoIncrementedInteger

50

• Boolean

true

false

• Color

"#e73435"

"rgba(255,255,255,40%)"

• Date (ISO 8601)

"YYYY-MM-DD"

• Datetime (ISO 8601)

"YYYY-MM-DDThh:mm:ss.sTZD"

• Decimal

6.5

• Enum:

2

"DirectOrder"

• Guid

"a101d668-e211-43c6-ae28-321b70696f43"

• Image

"productview/33/picture"

• Integer

2147483647

• Localizable string

{
    "en": "English string",
    "fr": "Chaîne en français"
}

• Long

9223372036854775807

• String

"Name"

• StringArray

[
    "First string",
    "Second string"
]