The new API Doc application brings API documentation directly into your Cumulocity tenant. It allows you to view the documentation of the Cumulocity Core API and of installed microservices, and to try out APIs using the current user session of the browser.
This provides several advantages:
- API documentation inside the platform: No need to point users to external documentation sites. The documentation shown always matches what is actually installed in the tenant.
- Try it out with your current session: Requests are executed with the current user session of the browser. No separate API client, no copying credentials — you explore and test endpoints with your own permissions in your own tenant.
- Microservices become self-documenting: Once a microservice opts in, its documentation appears automatically in every tenant where the service is subscribed. Documentation and deployment cannot drift apart.
- Faster onboarding: Team members, partners, and support engineers can discover and test APIs in the environment they will actually use them in.
The Cumulocity Core API documentation is included by default. Installed microservices need to opt in — more on that below.
Installation
The API Doc application is available as a blueprint (extension package). Install it like any other extension package by following the instructions in the Cumulocity documentation.
The sources are available on GitHub: Cumulocity-IoT/api-doc.
Registering your own microservice
To have your microservice show up in the API Doc application, two things are required:
- Your microservice serves an OpenAPI specification over HTTP (many frameworks generate this automatically).
- The microservice manifest contains an
openApiSpecproperty pointing to the relative path where the spec can be retrieved.
For example, an aggregation microservice using the context path aggregation and serving its OpenAPI spec under the relative path api-json, i.e., at /service/aggregation/api-json, would contain the following in its manifest:
{
"openApiSpec": "api-json"
}
That is all. The microservice’s API now appears in the API Doc application next to the Cumulocity Core API documentation.
Multiple specs per microservice
If a microservice exposes more than one OpenAPI spec, provide an array with a label for each spec:
{
"openApiSpec": [
{
"label": "Aggregation",
"path": "api-json"
},
{
"label": "Aggregation Admin",
"path": "admin-api-json"
}
]
}
Custom icon
You can provide a custom icon for your microservice via the manifest:
{
"icon": {
"class": "c8y-icon-enterprise"
}
}
Available icons can be found in the Cumulocity Design System icon overview. Note that icons from the dlt-c8y-icon subset require the dlt prefix, e.g., dlt-c8y-icon-truck.
Summary
The API Doc application turns your Cumulocity tenant into its own API portal: the Cumulocity Core API and custom microservices, documented and testable in one place. For microservice developers, opting in only requires exposing an OpenAPI spec and adding a single property to the manifest.
Note: To use the “Try it out” button with your microservice, the microservice must support the auth strategy used by the UI.
- Source Code: GitHub - Cumulocity-IoT/api-doc
- Installation instructions for extension packages: Cumulocity documentation
