← Specvane
DocumentationPrivacyEULASupport

Specvane documentation

Get started

  1. Install Specvane from the Atlassian Marketplace (Confluence admin). Every site gets a 30-day free trial. After that it is $2 a month for up to 10 users, then billed per user.
  2. Edit a Confluence page, type /specvane (or open the macro browser) and insert OpenAPI and Swagger (Specvane). The Specvane API docs editor opens straight away.
  3. Pick a spec file attached to the page, or add one with Upload a file or by pasting YAML or JSON and clicking Save as attachment.
  4. Check the Preview on the right, then click Save and publish the page.

Readers now see the API docs on the page. When you upload a new version of the attachment, the page shows the new version the next time it is opened (unless you pinned a version).

Specvane reads Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 files, in YAML or JSON, with the extension .yaml, .yml or .json.

Choose the spec file

The Spec file section of the editor decides where the spec comes from.

  • This page: lists every .yaml, .yml and .json file attached to the page you are editing, with its current version number. Pick one.
  • Another page: paste the page URL or ID into Paste the page URL or ID. Specvane shows that page's title (or Page not found or no access) and lists the spec files attached to it. Use this to show the same spec on several pages without copying the file.
  • Version: Always the latest (the default) follows the newest version of the attachment. Pick a specific version (each entry shows its number, date and upload comment) to pin the docs to that version. A pinned macro shows "pinned; latest is" with the newest version number next to the file name. Files the spec references with $ref (see "Specs split across several files") are pinned too: each loads at the version that was current when the pinned version of the main file was uploaded, and the docs say which versions they used. If a referenced file was first attached after that version, it has no matching earlier version, so its latest version is used and the docs say so.

If the page has no spec files yet, the editor says so and points you to the Add a spec section. On a page that has never been saved, save it once and then edit the macro to pick a file.

Add a spec

The Add a spec section is shown when the source is This page.

  • Upload a file: pick a .yaml, .yml or .json file from your computer (up to 8 MB). It is attached to the page.
  • Or paste YAML or JSON here: paste a document. As you paste, Specvane tells you the format and version it found (for example "OpenAPI 3.1.0, looks good.") or the first problem it found. Set the file name in the box next to Save as attachment (it starts as openapi.yaml) and click Save as attachment.

Saved specs are ordinary page attachments with version history. Saving with a name that already exists on the page adds a new version of that file, and the editor tells you which version it created. You can also save shared fragment files (for example a common.yaml with only schemas) this way; they are attached but not selected as the main spec.

Read the API docs

The top of the docs shows the API title, its version, a Swagger or OpenAPI badge with the spec version, the file name and version being shown (with the upload date when it is the latest version), and the API description.

  • Search: the box says "Search N endpoints (path, method, summary)". It matches the method, path, summary, operationId, description, tags and parameter names. Every word you type must match, so get orders works.
  • Server: if the spec lists servers, pick one from the dropdown. Request snippets use the server you pick.
  • Reference and List: readers can switch layouts at any time with these two buttons. The macro's saved layout is only the starting point.
    • Reference shows endpoints grouped by tag on the left and one endpoint in detail on the right.
    • List shows each tag as a section you expand, with each endpoint expanding inline.
  • Authentication: an expandable table of the spec's security schemes (type, scheme, header or query name, OAuth flows).
  • Schemas: an expandable list of every named schema. Click a schema to see its fields.
  • Spec check: at the bottom, a summary such as "Spec check: 0 errors, 1 warning, 2 notes". Expand it to see each problem with its location and line number (see "The spec check" below).

One endpoint in detail

  • The method, path, a deprecated badge if it applies, the summary and the operationId.
  • The description, and an Auth line with the security the endpoint needs (or "none required").
  • Path parameters, Query parameters, Headers and Cookies: tables with name, required and deprecated badges, type, description and example.
  • Request body: the media type (with a dropdown when there are several) and Schema or Example. Examples come from the spec, or are generated from the schema when the spec has none. Copy copies the example.
  • Responses: one tab per status code, with the description, response headers and the body schema or example.

The schema tree shows each field's type, required, deprecated, and chips such as nullable, read only, write only, constraints, defaults and allowed values. oneOf and anyOf show One of or Any of buttons to switch between the variants, with the discriminator when the spec has one. allOf is merged into one set of fields. Fields that refer back to themselves are marked "(circular reference)" instead of expanding forever. Generated request examples leave out read-only fields.

Descriptions support Markdown: headings, lists, tables, quotes, code, bold, italic and links. Only http, https and mailto links become links, and they open only when you click them. Raw HTML in descriptions is shown as text.

Copy a ready request

Next to each endpoint, the Request panel builds the call for you.

  1. Pick curl, HTTPie, JavaScript or Python.
  2. Type values into the parameter boxes. Required parameters are marked with *. Empty boxes use the example from the spec. Optional query and header parameters are only added when you type a value.
  3. If the endpoint takes a body, open Edit request body to change the generated example.
  4. Click Copy. The button shows Copied. If your browser blocks the clipboard inside Confluence it shows Select and copy; select the snippet text and copy it yourself.

Credentials are never filled in. Snippets use placeholders that read from your environment: $TOKEN for bearer and OAuth schemes, $BASIC_AUTH for basic auth, and the API key name in capitals (for example $X_API_KEY) for API keys. The JavaScript and Python snippets read the same names from environment variables.

There is no "Try it out" button. Specvane never sends a request to your API from Confluence, so there are no CORS errors and no tokens in the page. You run the snippet in your terminal or code, where your credentials already are.

Show what changed between versions

Under Show, switch from API docs to What changed.

  • Compare with: An earlier version of the selected file, or Another file: followed by any other spec file on the page.
  • Earlier version (when comparing with an earlier version): The version before (the default, so the report always compares the latest two versions) or a specific version.
  • Version of the other file (when comparing with another file): Latest or a specific version.
  • Breaking changes only: start the report showing breaking changes only. Readers can switch this with the same checkbox in the report.

The API changes report shows the two files and versions compared, counts of breaking changes, endpoints added, removed and changed, general changes (API version, title, servers), and then each endpoint that changed with every change labeled breaking, warning or info.

Changes marked breaking include:

  • an endpoint removed, or a 2xx response removed,
  • a parameter removed, a new required parameter, or a parameter that became required,
  • a parameter or field whose type changed,
  • a request body that became required, or a media type no longer accepted or returned,
  • a new required request field, or a request field that became required,
  • a response field removed,
  • an allowed value (enum) removed from a parameter or request field.

Warnings include endpoints newly marked deprecated, removed request fields, response fields that are no longer always returned, removed servers, and removed non-2xx responses. New endpoints, new optional parameters and fields, and summary changes are info.

Endpoints are matched by method and path, so /pets/{petId} and /pets/{id} count as the same endpoint. If the file has only one version, the macro says so and asks you to upload a new version of the file.

Specs split across several files

If your spec uses $ref to other files, for example common.yaml#/components/schemas/Address, attach those files to the same page as the main spec, with the same file names. Specvane loads them automatically (up to 25 files) and resolves references across them, including folder paths (only the file name is used).

References to URLs are not fetched. The spec check lists them as unresolved and asks you to attach the file to the page instead.

Display options

Under Show with API docs selected:

  • Layout: Reference (endpoint list + details) or List (sections you expand).
  • Start expanded (list): in the List layout, open Nothing, Tags (the default) or Everything when the page loads.
  • Toggles, all on by default: Title, Version, Description, Servers, Authentication, Schemas, Search box, Request snippets and Deprecated endpoints. Turning off Request snippets hides the Request panel; turning off Deprecated endpoints hides deprecated endpoints entirely.
  • Only these tags (none checked = all): show only endpoints with at least one of the checked tags.
  • Hide these tags: hide endpoints whose tags are all hidden.

The tag lists are filled from the selected spec. These options apply to readers on the page and to PDF and Word exports.

Max height in px (0 = fit content) applies in both modes. Set it to keep a long spec inside a scrolling box.

You can put several Specvane macros on one page, each with its own file and settings.

PDF and Word export

When you export a page to PDF or Word, each Specvane macro is written into the document as real content: the title, version, description, servers and authentication table, then a heading per tag and per endpoint with a parameters table, the request body media type with a JSON example, a responses table, and a JSON example for each response that has a JSON body, followed by a schemas table. Examples come from the spec, or are generated from the schema when the spec has none. The display toggles and tag filters on the macro apply. A What changed macro exports its summary and a table of every change.

The export runs as the person exporting, so it only includes specs that person can open.

The spec check

The spec check explains why a spec looks wrong on the page. It is a practical check, not a full validation. It reports:

  • syntax errors in YAML or JSON, with the line number,
  • unsupported versions (Swagger 1.x) and files that are not OpenAPI or Swagger documents,
  • $refs that cannot be resolved, with the reason,
  • path parameters used in the path but not declared, or declared but not in the path,
  • duplicate operationIds, parameters declared twice, and security schemes that are not defined,
  • endpoints with no responses or no success response, paths that do not start with /,
  • a missing title, version or paths, tags that are used but not declared, and specs with no servers (snippets then use relative URLs).

If the main file cannot be read at all, the macro shows the error and opens the spec check. When you click Save in the editor, Specvane checks the selected file and stops with the first problem if it cannot be read.

Licensing and trials

Specvane is paid through Atlassian: $2 a month for up to 10 users, then billed per user on Atlassian's graduated tiers, with a 30-day free trial that Atlassian runs. Manage the trial, subscription and invoices in Apps > Manage apps; billing and refunds are handled by Atlassian.

If the license is not active, every Specvane macro on the site shows "Specvane is not licensed on this site, so this API documentation is hidden. A Confluence admin can start a free trial or renew under Apps, Manage apps." PDF and Word exports show a one-line note instead of the docs. In the macro editor you can still pick a file and save the macro, but the Preview shows "Preview needs an active Specvane license." instead of the docs, and Upload a file and paste are turned off (you can still attach a file to the page with Confluence and pick it). Your spec attachments and macro settings are not touched, and the docs come back as soon as the license is active again.

Permissions and data

  • Specvane runs on Atlassian's Forge platform and sends nothing to any outside server. The app has no external network permissions and never calls the APIs described in your specs.
  • Specs are read through Confluence as the person viewing the page, with that person's Confluence permissions. Someone who cannot open a page cannot see a spec from it, including through Another page; they see "You do not have permission to view this page or its attachments."
  • The app stores nothing. It has no app storage. Your specs are ordinary page attachments with Confluence's own version history, and the macro settings are saved by Confluence in the page.
  • Values you type into the request builder stay in your browser and are discarded when you leave the page.
  • The permissions the app asks for: read attachments, download attachments, upload attachments (for Upload a file and Save as attachment, which run as you), and read page titles (for Another page).

Limits and known gaps

  • Spec files up to 8 MB. Swagger 2.0, OpenAPI 3.0 and 3.1 only; Swagger 1.x is not supported.
  • Files must end in .yaml, .yml or .json to appear in the file list.
  • $refs to URLs are not fetched; attach referenced files to the same page. Up to 25 referenced files per spec.
  • When the main file is pinned, referenced files are matched by upload time. A referenced file that was first attached after the pinned version loads at its latest version (the docs say so).
  • There is no "Try it out" button; requests are copied and run outside Confluence.
  • Webhooks in OpenAPI 3.1 specs are listed by name only.
  • Specs cannot be loaded from a URL, Git repository or file outside Confluence. Upload or paste them into a page.
  • Upload a file and paste are only available for This page. To use Another page, add the file on that page first.
  • PDF and Word exports include request and response examples for JSON bodies only (not XML or form bodies), and list schemas in a table rather than the full schema tree.

FAQ

"Try it out" never worked for us inside Confluence. What do we get instead? A request builder. Fill in parameters, pick curl, HTTPie, JavaScript or Python, and copy a request that runs from your terminal or code. Nothing is sent from the page, so there are no CORS or "Load failed" errors.

Will our access tokens show up in the page or in edit mode? No. Specs come from page attachments, so there is no token or repository credential in the macro settings. Snippets use placeholders such as $TOKEN.

Can we hide the title, version or servers, or show only some tags? Yes. Title, version, description, servers, authentication, schemas, search, request snippets and deprecated endpoints each have a toggle, and you can show only some tags or hide others.

Can we put more than one spec on a page? Yes. Each macro loads its own file with its own settings.

How do we see what changed in a new release? Upload the new version over the old attachment (same file name) and add a macro set to What changed. It compares the latest two versions and flags breaking changes.

Does PDF export show the docs or an empty box? The docs: headings, parameter and response tables, and request and response examples for JSON bodies.

Our spec is split into several files. Does that work? Yes, when the referenced files are attached to the same page.

Can we keep the docs on one page and show them elsewhere? Yes. Use Another page in the editor to read the spec from the page where it is attached.

We are moving from Confluence Data Center. What happens to our specs? Spec files attached to pages move with the pages. Edit each page, insert Specvane and pick the attachment that came across. Macros from other apps are not converted automatically.

Uninstalling and your data

Specvane stores nothing of its own, so there is no app data to delete. Your spec files stay on their pages as normal attachments with their full version history. After you uninstall, the Specvane macros on your pages no longer render.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing) or email hello@greatwork.company. First response within 1 business day (US Central time). Security reports get a first response within 4 hours.