Legilio API Docs for Confluence Install from Marketplace

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.

Install

A Confluence site admin installs Legilio once, from its Atlassian Marketplace listing. After that, anyone who can edit a page can add the macro. Moving pages from another OpenAPI or Swagger macro? Follow the migration guide.

Add the macro

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

The settings check the spec as you type or pick a file. They show the OpenAPI or Swagger version, the API title and the list of operations, or the line with an error. A spec with errors can still be saved; the page then shows the error instead of the docs.

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. Use the Petstore sample fills in an example. To update the spec, replace the text in the macro settings.

Page attachment. Attach a .yaml, .yml or .json file to the page, then pick it in the macro settings. For several versions of an API, attach one file per version and add a macro for each. To update the spec, upload the new file under the same name: Confluence keeps it as a new version, and the macro shows the latest one.

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 (see Admin settings).

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.

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.

Copy as cURL

In Swagger UI, each operation has a Copy as cURL button. Redoc shows the same command under Request samples. The command uses the server and the example values from the spec; in Swagger UI, it uses the server you pick under Servers. Check the values and run it in a terminal.

Legilio never sends requests itself, so Swagger UI has no Try it out or Authorize.

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.
Couldn’t show the spec
Swagger UI or Redoc failed to load or stopped on something in the spec. Reload the page. If the message stays, open a support request with its text.
Legilio isn’t licensed on this site
The subscription has ended or hasn’t started. Ask your site admin to subscribe or renew.

Limits

Support

Questions, bug reports and feature requests: open a request in the support portal or write to support@xoma.me. We answer Monday to Friday, 9:00–18:00 Kyiv time, and aim to reply within one working day.