Scalar UI in Yelix

Yelix provides a built-in method to easily expose your OpenAPI documentation with Scalar UI. This creates a beautiful, interactive API documentation interface.

Quick Setup

The easiest way to add Scalar UI is using the exposeScalarOpenAPI() method:

import { YelixHono } from '@yelix/hono';

const app = new YelixHono();

// Configure your API
app.__openapi.setTitle('My API');
app.__openapi.setDescription('API Documentation');

// Add your routes here...
app.get('/users', (c) => {
  return c.json({ users: [] });
});

// Expose Scalar UI (creates /openapi.json and /docs endpoints)
app.exposeScalarOpenAPI({
  title: 'My API Documentation',
  openapiJsonPath: '/openapi.json',
  docsPath: '/docs',
});

Customization Options

You can customize the paths and title:

app.exposeScalarOpenAPI({
  title: 'My Custom API Docs',
  description: 'Detailed API documentation',
  openapiJsonPath: '/api/openapi.json',  // Custom OpenAPI JSON path
  docsPath: '/api-docs',                  // Custom docs page path
});

Manual Setup (Advanced)

If you need more control, you can set it up manually:

import { YelixHono, openapi } from '@yelix/hono';

const app = new YelixHono();

// Expose OpenAPI JSON
app.get('/openapi.json', openapi({ hide: true }), (c) => {
  return c.json(app.getOpenAPI());
});

// Expose Scalar UI page
app.get('/docs', openapi({ hide: true }), (c) => {
  return c.html(`<!doctype html>
<html>
  <head>
    <title>API Documentation</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>
      var configuration = {};
      document.getElementById('api-reference').dataset.configuration =
        JSON.stringify(configuration);
    </script>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
  </body>
</html>`);
});

Accessing Your Documentation

After setting up Scalar UI, you can access:

OpenAPI JSON: http://localhost:8000/openapi.json
Documentation UI: http://localhost:8000/docs

The Scalar UI provides an interactive interface where you can:

Browse all your API endpoints
See request/response schemas
Test endpoints directly from the documentation
View authentication requirements