Klob Apps

SpecLens documentation

OpenAPI and AsyncAPI documentation inside Confluence Cloud.

Get started

  1. Install SpecLens from the Atlassian Marketplace (a Confluence admin does this once).
  2. On a page or blog post, attach your specification: .yaml, .yml or .json. No file at hand? Try sample-openapi.yaml.
  3. Type /SpecLens in the editor and insert SpecLens API docs.
  4. 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

Swagger UI rendering of an Orders API inside a Confluence page
OpenAPI with Swagger UI, the default viewer.
Redoc rendering with its menu and search beside the content
Redoc opens in a frame with its own menu, search and scroll.
AsyncAPI viewer showing the Kafka server and the operations of an event-driven API
AsyncAPI 2 and 3 with the AsyncAPI viewer.

Settings

SettingWhat it does
Where is the specification?A file attached to the same page, or the content pasted inside the macro.
Attached fileThe 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 SwaggerAutomatic (Swagger UI), Swagger UI or Redoc. AsyncAPI always uses the AsyncAPI viewer.
Initial layoutSwagger UI only: operations as a list, all expanded, or all collapsed.
Show schemas sectionSwagger UI only: show or hide the models/schemas section.

Supported specifications

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:

  1. Open Settings › SpecLens: OpenAPI (Swagger) & AsyncAPI Docs – Migration in Confluence and choose a space.
  2. Scan. Nothing changes yet: the list shows, page by page, what each macro becomes or what it needs.
  3. 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.
  4. Something looks wrong? Undo the page on the same screen, or restore the previous version from the page history later.
The old macro hasIt becomes
The specification pasted insideSpecLens with the same text pasted inside
A file attached to the pageSpecLens reading that attachment
A URLSpecLens 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

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

MessageWhat to do
Choose a specificationEdit the macro and pick a file, or switch to pasted content.
Paste your specificationPaste 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 emptyThe file or the macro body has no content.
The specification is too largeSpecLens reads specifications up to 5 MB. Split the file or remove unused parts.
The viewer could not display this specificationValidate the specification, or try the other OpenAPI viewer in the settings.
SpecLens needs an active licenseAsk a Confluence admin to renew SpecLens in Apps > Manage apps.
SpecLens could not startReload the page. If it keeps happening, contact support.

When the title is The specification could not be loaded, the text below it says why:

ReasonWhat 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

MessageWhat to do
No YAML or JSON files attachedAttach the specification to the page, then use Refresh list.
Attachments could not be listedCheck that you can view the page's attachments, then use Refresh list.
The file chosen before is no longer attachedChoose another file.
This file is larger than 5 MBSpecLens reads specifications up to 5 MB. Split the file or remove unused parts.
The settings could not be loadedClose 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.