Interactive docs with Scalar
We have a spec being served at /openapi.json. A developer can fetch it and read the raw JSON, but nobody wants to read raw JSON. What they want is an interactive page where they can browse endpoints, see schemas, expand examples, and try out requests without leaving the browser.
That’s what documentation UIs do. They read your OpenAPI spec and render it as a fully interactive web page.
Scalar: built into @hectoday/openapi
When you called api.docs(route) in the previous lesson, it created a GET /docs endpoint that serves Scalar, a modern API documentation UI. If you open http://localhost:3000/docs in your browser, you’ll see the interactive documentation for your entire API.
Under the hood, api.docs(route) serves an HTML page that loads Scalar from a CDN and points it at your /openapi.json endpoint:
<!doctype html>
<html>
<head>
<title>API Reference</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<script id="api-reference" data-url="/openapi.json"></script>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
</body>
</html>That’s all it takes. Scalar fetches the spec and renders the full interactive documentation. You don’t need to configure anything. It reads the tags, groups endpoints into sections, renders schemas as expandable trees, and provides a built-in API client for testing.
What Scalar gives you
Endpoint browsing. Endpoints are grouped by the tags we defined in the openapi() config. Click a section to expand it. Click an endpoint to see its parameters, request body, and responses.
Code examples. For every endpoint, Scalar shows code examples in multiple languages: curl, JavaScript, Python, and more. Clients can copy-paste the example that matches their stack.
Try it out. Scalar includes a built-in API client. Clients can fill in parameters, write a request body, and send the request directly from the docs. The response shows up right there in the UI.
Authentication. Scalar reads the security schemes from the spec and lets clients enter their Bearer token. All subsequent requests include the token automatically. The lock icon shows which endpoints require auth.
Schema display. Schemas are rendered as interactive trees. Required fields are marked. Enum values are listed. Nested objects are expandable. Clients can see the full shape of every request and response at a glance.
In the next lesson, we will take the spec even further and generate a fully typed TypeScript client from it, so frontend developers get autocompletion and compile-time safety for every API call.
Exercises
Exercise 1: Open /docs in your browser. Browse through the endpoints. Expand a few and look at the schemas and examples.
Exercise 2: Use the built-in API client in Scalar to make a GET request. Then try a POST request with a JSON body.
Exercise 3: Click the auth section and enter a Bearer token. Make an authenticated request from the docs.
Why serve interactive docs directly from the API instead of a separate documentation site?