How to Embed Interactive API Docs
in Confluence in 5 Minutes
A step-by-step guide to turning your OpenAPI spec into a live, testable reference — right inside your Confluence space.
If your team uses Confluence as a central knowledge hub and maintains an OpenAPI specification for your API, you’re one macro away from having interactive documentation that your entire organization can read, explore, and test without leaving the wiki.
This guide walks through exactly how to do it with Stoplight Elements for Confluence — from installation to a live, working embed in under five minutes.
Step 1 — Install the App from the Marketplace
Go to the Stoplight Elements for Confluence listing on the Atlassian Marketplace and click Try it free. Select your Confluence Cloud site and confirm the installation.
The app is built on Atlassian Forge, so there’s no external server to configure and no data leaves your Atlassian environment. The installation takes about 60 seconds and requires no technical setup beyond clicking through the standard Marketplace flow.
Step 2 — Open or Create a Confluence Page
Navigate to the Confluence space where you want your API documentation to live. This could be an existing page — your engineering wiki, a service runbook, an onboarding guide — or a brand new page dedicated to the API reference.
For teams setting this up for the first time, a good starting structure is a top-level page called something like “API Reference” or “[Service Name] API Docs”, with child pages per major API version or service if you have multiple.
Step 3 — Insert the Stoplight Elements Macro
In the Confluence page editor, type /Stoplight in the body of the page. The macro picker will show the Stoplight Elements macro — click it to insert.
You’ll see a configuration panel appear. This is where you connect the macro to your OpenAPI spec. You have two options:
Option A — Paste a URL
If your OpenAPI spec is hosted somewhere publicly accessible — a GitHub raw URL, a CDN, your own API server — paste the URL into the spec URL field. The macro will fetch and render it every time the page loads, so your docs always reflect the latest version of the spec automatically.
Option B — Paste YAML or JSON directly
If your spec isn’t hosted publicly, paste the raw YAML or JSON content directly into the inline spec field in the macro configuration. This is the simplest option for internal APIs or specs that live behind authentication.
Step 4 — Save and Publish
Once you’ve connected the spec, click Save in the macro configuration panel, then publish the Confluence page. The macro renders immediately — no additional steps, no build process, no waiting.
What your team sees is a clean three-panel layout:
Step 5 — Share with Your Team
The Confluence page with embedded API docs behaves like any other Confluence page — it respects your existing space permissions, appears in search, and can be linked from other pages, onboarding docs, or Jira tickets.
A few things worth doing after publishing:
What You’ve Built in 5 Minutes
A Confluence page that renders your full OpenAPI spec as a navigable, interactive reference — with a live Try It console — that updates automatically when your spec changes. No separate documentation site. No manual publishing workflow. No drift between spec and docs.
Every engineer, product manager, and QA team member on your Confluence site can now read, explore, and test your API without leaving the wiki or setting up any additional tooling.
Your API Docs Are 5 Minutes Away.
Install Stoplight Elements for Confluence free and have interactive API documentation live in your wiki before your next standup.
Try It Free on the MarketplaceQuestions? Visit the support portal.