Stoplight Elements — Embeddable Interactive API Documentation
In this tutorial, you will learn about Stoplight Elements. We cover key concepts, practical examples, and best practices to help you master this topic.
Stoplight Elements is an open-source web component library that renders OpenAPI specifications as interactive documentation with Try It Out consoles, code samples, and schema browsing.
In this tutorial, you will learn how to embed Stoplight Elements in any web page, customize its appearance, configure its behavior, and use it alongside other documentation tools.
What You'll Learn
You will learn how to install and configure Stoplight Elements, customize its appearance with CSS variables, use its different layout options, and embed it in React, Vue, or plain HTML applications.
Why It Matters
Stoplight Elements combines the clean reading experience of Redoc with the interactive Try It Out functionality of Swagger UI in a single component. It is the most modern option for embedding API documentation in your developer portal.
Real-World Use
DodaTech uses Stoplight Elements as the primary documentation component in the developer portal. The elements-api component renders the full API reference, and elements-dev-portal provides a complete documentation hub with guides and articles alongside the API reference.
flowchart LR A[OpenAPI Spec] --> B[Stoplight Elements] B --> C[API Reference] B --> D[Try It Out] B --> E[Code Samples] B --> F[Schema Browser] B:::current classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
Installation
Script Tag
<!DOCTYPE html>
<html>
<head>
<title>DodaTech API Reference</title>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
</head>
<body>
<div id="api-docs" style="height: 100vh;"></div>
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<script>
const api = document.createElement("elements-api");
api.apiDescriptionUrl = "/openapi.yaml";
api.router = "hash";
api.layout = "sidebar";
document.getElementById("api-docs").appendChild(api);
</script>
</body>
</html>
React
npm install @stoplight/elements
import { API } from "@stoplight/elements";
import "@stoplight/elements/styles.min.css";
function ApiDocs() {
return (
<API
apiDescriptionUrl="/openapi.yaml"
router="hash"
layout="sidebar"
tryItCredentialsPolicy="same-origin"
/>
);
}
Vue
<template>
<div id="api-docs" style="height: 100vh">
<elements-api
:apiDescriptionUrl="apiUrl"
router="hash"
layout="sidebar"
/>
</div>
</template>
<script>
import "@stoplight/elements/web-components.min.js";
import "@stoplight/elements/styles.min.css";
export default {
data() {
return {
apiUrl: "/openapi.yaml"
};
}
};
</script>
Layout Options
Sidebar Layout
Best for comprehensive API references:
const options = {
layout: "sidebar",
router: "hash",
sidebar: {
showServers: true,
showOperations: true,
showModels: true
}
};
Stacked Layout
Best for simple APIs:
const options = {
layout: "stacked",
router: "hash"
};
Customization
Stoplight Elements uses CSS custom properties for theming:
/* In your stylesheet */
:root {
--theme-primary: #ff6600;
--theme-bg: #ffffff;
--theme-text: #333333;
--theme-heading: #111111;
--theme-link: #ff6600;
--theme-code-header: #f5f5f5;
--theme-code-bg: #f8f9fa;
--theme-sidebar-bg: #fafafa;
--theme-sidebar-text: #333333;
--theme-sidebar-active: #ff6600;
--theme-try-it-btn-bg: #ff6600;
--theme-success: #28a745;
--theme-error: #dc3545;
--theme-warning: #ffc107;
}
Advanced Configuration
const api = document.createElement("elements-api");
api.apiDescriptionUrl = "/openapi.yaml";
api.router = "hash";
api.layout = "sidebar";
// Try It Out configuration
api.tryItCredentialsPolicy = "same-origin";
api.tryItCorsProxy = "/cors-proxy";
// Mock server
api.mockServerUrl = "https://stoplight.io/mocks/dodatech/api/123";
// Hide elements
api.hideTryIt = false;
api.hideSchemas = false;
api.hideInternal = true;
// Code samples
api.defaultSampleLanguage = "python";
Developer Portal Component
Elements also provides a full developer portal component:
import { DeveloperPortal } from "@stoplight/elements";
function DevPortal() {
return (
<DeveloperPortal
platformUrl="https://dodatech.stoplight.io"
projectId="abc123"
projectPublishId="def456"
router="hash"
/>
);
}
Common Mistakes
No height set on container — Elements requires an explicit height on its container. Always set
height: 100vhor a specific pixel height.Missing CORS proxy — Try It Out makes browser requests. If your API does not support CORS, configure tryItCorsProxy.
Not hiding internal paths — Exposing internal-only endpoints in public docs. Use hideInternal to suppress paths marked with x-internal: true.
Loading multiple Elements instances — Elements is heavy. Load one instance per page. Use tabbed navigation to switch between API specs.
Forgetting the CSS import — Elements requires the stylesheet. Without it, the component renders unstyled and broken.
Practice Questions
- What are the two layout options for Stoplight Elements?
- How do you customize the theme colors in Stoplight Elements?
- What is the purpose of the tryItCorsProxy option?
- How do you hide internal endpoints from documentation?
- How do you set a default code sample language?
Challenge
Create a developer portal page that uses Stoplight Elements to render an OpenAPI spec. Configure sidebar layout, custom theme with your brand colors, CORS proxy for Try It Out, and disable schema browsing. Embed it in a React application with routing.
FAQ
Mini Project
Build a documentation page for a weather API using Stoplight Elements. Configure a custom theme with blue primary colors, sidebar layout, enable Try It Out with a CORS proxy, set Python as the default code sample language, and hide internal testing endpoints using x-internal tags.
What's Next
In the next lesson, you will learn how to use Postman for API documentation and how to publish collections as interactive docs.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro