SpecLens documentation

OpenAPI and AsyncAPI documentation inside Confluence Cloud.

Get started

Install SpecLens from the Atlassian Marketplace (a Confluence admin does this once).
On a page, attach your specification: .yaml, .yml or .json.
Type /SpecLens in the editor and insert SpecLens API docs.
In the settings, choose A file attached to this page and pick your file. Save and publish.

Prefer not to attach a file? Choose Pasted inside the macro and paste the specification in a code block inside the macro.

Settings

Setting	What it does
Where is the specification?	A file attached to the same page, or the content pasted inside the macro.
Viewer for OpenAPI and Swagger	Automatic (Swagger UI), Swagger UI or Redoc. AsyncAPI always uses the AsyncAPI viewer.
Initial layout	Swagger UI only: operations as a list, all expanded, or all collapsed.
Show schemas section	Swagger UI only: show or hide the models/schemas section.

Supported specifications

OpenAPI 3.0 and 3.1, Swagger 2.0 (YAML or JSON).
AsyncAPI 2.x and 3.x.
Any other JSON or YAML is shown as a collapsible tree.

Export to PDF and Word

When a page is exported, each SpecLens macro becomes a summary: title, version, servers and a table of every operation (OpenAPI/Swagger) or channel (AsyncAPI).

Limitations, on purpose

No "Try it out". Sending requests from Confluence to your API servers would require data to leave Atlassian.
External references are not fetched. $ref pointing to other URLs is not downloaded for the same reason. Bundle your specification into one file (for example with redocly bundle or swagger-cli bundle).
Size. Up to 5 MB per specification.

Troubleshooting

Message	What to do
Choose a specification	Edit the macro and pick a file, or switch to pasted content.
The selected file is no longer attached to this page	The attachment was deleted or moved. Pick another file.
Syntax error (line X, column Y)	Fix the YAML/JSON at that position. Indentation errors are the most common cause.
The viewer could not display this specification	Validate the specification, or try the other OpenAPI viewer in the settings.
SpecLens needs an active license	Ask a Confluence admin to renew SpecLens in Apps > Manage apps.

Need help?

See Support.