OpenAPI Document
Platform 6 can describe its whole REST API as an OpenAPI document, generated from the JAX-RS resources of every deployed service.
Enabling the document¶
The document is disabled by default. Enable it with the p6.openapi.enabled configuration key, or with the
p6_openapi_enabled environment variable:
p6.openapi.enabled: true
Three endpoints are then served under the /p6 application path:
| Endpoint | Returns |
|---|---|
/p6/openapi.json |
the document as JSON |
/p6/openapi.yaml |
the document as YAML |
/p6/openapi |
JSON or YAML, negotiated from the Accept header |
Warning
The document describes every endpoint of every deployed service. Enable it deliberately, and treat the endpoints above as you would the rest of the Service REST API when exposing an instance.
Coverage¶
The document lists the resources of every service deployed at the time it is served, built-in services and custom services alike. Services register their JAX-RS resources progressively while they deploy, and a service deployed or undeployed after start-up reloads the JAX-RS container. Platform 6 rebuilds the OpenAPI description on each of those reloads, so the served document always matches the resources currently registered — no restart is needed to pick up a newly deployed service, and none is needed to drop an undeployed one.
Describing your own resources¶
Resources are described from their JAX-RS annotations, so a resource is listed as soon as its service registers it. Use
the Swagger
annotations (@Operation, @Parameter, @Schema, …) to add summaries, descriptions and schemas on top of them.
Document metadata¶
The info block of the document is taken from configuration:
| Key | Default |
|---|---|
p6.swagger.ui.version |
1.1.0 |
p6.swagger.ui.title |
Platform 6 Services API |
p6.swagger.ui.description |
Platform 6 Resources |
p6.swagger.ui.contact.name |
Platform 6 R&D |
p6.swagger.ui.contact.email |
rd@platform6.io |
p6.swagger.ui.cache.ttl.millis |
-1 |
p6.swagger.ui.cache.ttl.millis controls how long a generated document is reused before the resources are scanned
again: -1 keeps it until the next container reload, 0 scans on every request, and a positive value is a lifetime in
milliseconds. The default is appropriate for most instances, because a reload already refreshes the document; lower it
only when profiling resource scanning.