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 or blog post, attach your specification:
.yaml,.ymlor.json. No file at hand? Try sample-openapi.yaml. - Type
/SpecLensin the editor and insert SpecLens API docs. - In the settings, choose A file attached to this page and pick your file. Save and publish. Leave the box inside the macro empty: it is only for pasted specifications.
Prefer not to attach a file? Choose Pasted inside the macro and paste the specification in a code block inside the macro.
What readers see



Settings
| Setting | What it does |
|---|---|
| Where is the specification? | A file attached to the same page, or the content pasted inside the macro. |
| Attached file | The YAML or JSON files of the page, with their size. Attached a file while the settings were open? Use Refresh list. |
| 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.
Authentication schemes
Swagger UI lists the security schemes of the specification (HTTP, API key, OAuth 2.0, OpenID Connect) under the title, and operations that need one keep their lock icon. There is no Authorize dialog: SpecLens never sends requests, so a token would have nowhere to go.
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).
Migrating from another OpenAPI app
A Confluence admin can replace the macros of Open API (Swagger) Integration, Visualize OpenAPI (Swagger) documentation, Swagger UI for Confluence and Open API (Swagger) Editor for Confluence with SpecLens, space by space:
- Open Settings › SpecLens: OpenAPI (Swagger) & AsyncAPI Docs – Migration in Confluence and choose a space.
- Scan. Nothing changes yet: the list shows, page by page, what each macro becomes or what it needs.
- Migrate. SpecLens edits each page as you, so it only changes pages you can edit, and each page gets a new version in its history.
- Something looks wrong? Undo the page on the same screen, or restore the previous version from the page history later.
| The old macro has | It becomes |
|---|---|
| The specification pasted inside | SpecLens with the same text pasted inside |
| A file attached to the page | SpecLens reading that attachment |
| A URL | SpecLens reading the attachment of the page with the same file name. SpecLens never downloads from outside Atlassian: if the file is not attached, the scan says which one to attach |
Macros inside tables, panels, lists or other macros are listed but not changed: move them out and scan again. Credentials kept in the old macros (user names, passwords, tokens) are never copied; they remain in the page history, so change them. The AsyncAPI macro of Open API (Swagger) Integration stores its content on that app's servers and cannot be migrated.
The scan finds pages through Confluence search, which catches up with edits a few minutes later: a page you just undid or restored from its history can take several minutes to show up in a new scan.
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.
$refpointing to other URLs or files is not downloaded for the same reason. Bundle your specification into one file (for example withredocly bundleorswagger-cli bundle). - Size. Up to 5 MB per specification. With more than 500 operations Swagger UI opens collapsed by tag, with a tag filter, so the page stays responsive.
Copying pages
When you copy a page with its attachments, Confluence gives the copied files new ids. SpecLens remembers the file name, so the copy shows its own attachment without editing the macro.
Public spaces
If your site and space allow anonymous access, visitors who are not logged in see the documentation too. SpecLens reads the attachment with its own permission, so they are never asked to grant access.
Troubleshooting
On the page
| Message | What to do |
|---|---|
| Choose a specification | Edit the macro and pick a file, or switch to pasted content. |
| Paste your specification | Paste the OpenAPI or AsyncAPI YAML/JSON inside the macro, ideally in a code block. |
| Syntax error in file (line X, column Y) | The lines around the error are shown under the message, with a caret under the column. Indentation is the most common cause. |
| The specification is empty | The file or the macro body has no content. |
| The specification is too large | SpecLens reads specifications up to 5 MB. Split the file or remove unused parts. |
| 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. |
| SpecLens could not start | Reload the page. If it keeps happening, contact support. |
When the title is The specification could not be loaded, the text below it says why:
| Reason | What to do |
|---|---|
| The selected file is no longer attached to this page. | The attachment was deleted or renamed. Edit the macro and pick another file. |
| The specification is larger than 5 MB. | Split it or remove unused parts. |
| Confluence did not return the attachments of this page. | Check that you can view the page's attachments, then reload. |
| Confluence did not return the file. | Check that you can open the attachment, then reload. |
| This specification is large and your browser could not unpack it. | Large specifications travel compressed. Update your browser to a current version and reload. |
| The selected attachment is not valid. | Edit the macro and choose the file again. |
| SpecLens could not tell which page it is on. | Reload the page. |
| Something went wrong while reading the attachment. | Reload the page. If it keeps happening, contact support. |
In the macro settings
| Message | What to do |
|---|---|
| No YAML or JSON files attached | Attach the specification to the page, then use Refresh list. |
| Attachments could not be listed | Check that you can view the page's attachments, then use Refresh list. |
| The file chosen before is no longer attached | Choose another file. |
| This file is larger than 5 MB | SpecLens reads specifications up to 5 MB. Split the file or remove unused parts. |
| The settings could not be loaded | Close the panel and open the macro settings again. |
In PDF and Word exports
A line starting with SpecLens: replaces the summary and says why, for example that the selected file is no longer attached. Fix it on the page and export again.
Need help?
See Support.