Legilio documentation

Legilio shows OpenAPI and Swagger specs as API documentation on Confluence Cloud pages, rendered with Swagger UI or Redoc. It runs on Atlassian, so your specs never leave it.

Add the macro

Edit a page and type /legilio. Searching for OpenAPI or Swagger finds it too.
Pick Legilio API Docs. The macro settings open.
Choose Swagger UI or Redoc, paste the spec or pick an attachment, and click Save.

To change the settings later, select the macro and click the pencil icon on its toolbar.

Where the spec comes from

Paste YAML or JSON. The spec is saved in the macro, like any other page content. This suits small specs and specs that live only in Confluence. Use the Petstore sample fills in an example.

Page attachment. Attach a .yaml, .yml or .json file to the page, then pick it in the macro settings. This suits large specs and pages that show several versions of an API: add one macro per file.

Both sources take OpenAPI 3.0, 3.1 and Swagger 2.0. If your admin allows only one of them, the settings show only that one.

Legilio doesn’t load specs from URLs or Git repositories, because it never connects to anything outside Atlassian. Download the file and attach it to the page instead.

Update a spec

For a pasted spec, open the macro settings and replace the text.

For an attachment, upload the new file under the same name. Confluence stores it as a new version of the same attachment, and the macro shows the latest version.

Swagger UI or Redoc

Swagger UI lists operations grouped by tag. Type in Filter by tag to narrow the list. Redoc shows the whole spec as one reference with a navigation menu. You can switch between them at any time in the macro settings.

Both follow the Confluence light or dark theme. Try it out and Authorize are turned off in Swagger UI, so nobody can send requests to your API from the page.

Export

Word. The macro turns into a summary of the spec: title, version, description, servers, a table of endpoints for each tag with their parameters, and the list of schemas.

PDF. The docs print as rendered. Specs with more than 50 operations or 100 schemas print as the same summary as in Word, because rendering them in full would break the export.

Admin settings

Confluence admins decide which sources macros may use: specs pasted into the macro, page attachments, or both. In Atlassian Administration, open your site’s Connected apps, find Legilio, click … and choose Configure.

A macro that uses a source you turn off shows a notice instead of the docs. Nothing is deleted: turn the source back on, and the docs return.

Messages

No spec yet: The macro is empty. Open its settings and paste a spec or pick an attachment.
The spec isn’t valid YAML or JSON: The message names the line and column of the error. Fix the file there.
This doesn’t look like an OpenAPI or Swagger spec: The file has no openapi or swagger field at the top level.
The attachment isn’t available: The file was deleted, or the reader isn’t allowed to view it.
Your Confluence admin has turned off…: The macro uses a source your admin doesn’t allow. Edit the macro to use the other source.
Legilio isn’t licensed on this site: The subscription has ended or hasn’t started. Ask your site admin to subscribe or renew.

Limits

Specs come only from the macro or from attachments of the same page.
Swagger UI has no Try it out or Authorize, and Redoc has no search.
The interface is in English.

Moving from another app

To move pages from another OpenAPI or Swagger macro, follow the migration guides.

Support

Questions, bug reports and feature requests: open a request in the support portal or write to ask@xoma.me.