Code Playground (Swagger UI) in Developer Portals
Interactive code playgrounds let developers test API calls directly from the documentation. Learn how to integrate Swagger UI and build custom playgrounds that reduce time to first successful API call.
What You'll Learn
You will learn how to integrate interactive API playgrounds into your developer portal using Swagger UI, how to configure them for your API, and how to customize the developer experience.
Why It Matters
Interactive playgrounds let developers try API calls without leaving the documentation. This reduces the time from reading about an endpoint to successfully calling it. Playgrounds are the most appreciated feature in developer portals.
Real-World Use
The Durga Antivirus Pro developer portal uses Swagger UI for the interactive playground. Every endpoint page includes a Try It section where developers can enter parameters, authenticate, and see live responses.
flowchart LR A[Developer Finds Endpoint] --> B[Enters Parameters] B --> C[Clicks Try It] C --> D[API Call Made] D --> E[Live Response Shown] E --> F[Copy Code Examples] A:::current classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
Swagger UI Integration
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet"
href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script
src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js">
</script>
<script>
const ui = SwaggerUIBundle({
url: "/openapi.yaml",
dom_id: "#swagger-ui",
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "BaseLayout",
deepLinking: true,
showExtensions: true,
showCommonExtensions: true
});
</script>
</body>
</html>
Custom Playground with React
import React, { useState } from 'react';
function ApiPlayground({ endpoint, method, parameters }) {
const [params, setParams] = useState({});
const [response, setResponse] = useState(null);
const [loading, setLoading] = useState(false);
async function executeCall() {
setLoading(true);
try {
const queryString = Object.entries(params)
.map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
.join('&');
const url = `https://api.example.com${endpoint}?${queryString}`;
const res = await fetch(url, {
method: method,
headers: { Authorization: `Bearer ${API_KEY}` }
});
const data = await res.json();
setResponse({ status: res.status, data });
} catch (error) {
setResponse({ status: 'error', error: error.message });
}
setLoading(false);
}
return (
<div className="playground">
<h3>Try It Yourself</h3>
{parameters.map(param => (
<div key={param.name}>
<label>{param.name}</label>
<input
type="text"
placeholder={param.description}
onChange={(e) => setParams({...params, [param.name]: e.target.value})}
/>
</div>
))}
<button onClick={executeCall} disabled={loading}>
{loading ? 'Running...' : 'Execute'}
</button>
{response && (
<pre>{JSON.stringify(response, null, 2)}</pre>
)}
</div>
);
}
Pre-Filled Example Requests
When the page loads, pre-fill the playground with working examples:
// Pre-fill parameters with example values
const defaultParams = {
limit: 5,
severity: "critical",
api_key: "dga_sandbox_key_demo"
};
Common Mistakes
1. No Sandbox Environment
Pointing the playground at the production API risks data corruption. Always use a sandbox environment.
2. Pre-Filled Authentication
Do not pre-fill real API keys. Use sandbox keys or require developers to enter their own.
3. Missing Error Responses
The playground should display both successful responses and error responses with explanations.
4. No Rate Limit Handling
APIs have rate limits. The playground should handle 429 responses gracefully and inform the developer.
5. Ignoring Mobile Users
Playgrounds with complex UIs may not work on mobile. Provide a simplified mobile view or alternative curl commands.
Practice Questions
1. What is the primary benefit of an interactive API playground?
It lets developers test API calls directly from the documentation, reducing time to first successful call.
2. Why should the playground use a sandbox environment?
Sandbox environments prevent accidental data modification and allow experimentation without risk.
3. What information should the playground display after an API call?
HTTP status code, response headers, response body, and the equivalent curl command.
4. How should authentication be handled in the playground?
Require developers to enter their own API key. Use sandbox keys for demo purposes.
5. Challenge: Integrate Swagger UI into a documentation page for an API with three endpoints. Configure it with a sandbox base URL, pre-filled example parameters, and the ability to show the equivalent curl command for each request.
FAQ
Mini Project
Integrate Swagger UI into a developer portal page for the Durga Antivirus Pro threat intelligence API. Configure it with a sandbox base URL, pre-filled authentication, example parameters, and display both successful responses and error responses.
What's Next
With the playground in place, learn about Authentication Setup documentation to help developers configure API keys, OAuth, and other authentication methods correctly.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro