The Nightmare of Using Swagger UI in Real-World Projects
After 6 months of deploying a transaction management system for a Japanese partner, I realized a critical issue: API documentation. Even though the backend code was clean and used swagger-jsdoc for automation, the default Swagger UI interface still caused constant complaints from the partner’s Frontend and Testing teams.
The problem wasn’t the data, but the User Experience (UX). Swagger UI looks like a website from 2010. Searching for an endpoint in a list of over 200 APIs is a total chore. The “Try it out” feature often struggles with nested objects, and the returned JSON format is hard to read when dealing with large datasets.
Why Swagger UI is No Longer the Top Choice?
Swagger UI has been the industry standard for a decade. However, as Developer Experience (DX) requirements become more demanding, it has started to show unacceptable limitations:
- Outdated interface: Customizing CSS to match a project’s branding is extremely complex. Sometimes, even a small layout tweak can break the entire page.
- Poor performance: With OpenAPI files (JSON/YAML) around 10,000 lines long, browsers often freeze or lag while scrolling.
- Poor API Client: It simply sends requests. You can’t manage environment variables or save tokens in professional collections like you can in Postman.
I once refactored a 50,000-line codebase. The lesson learned was that good API documentation saves at least 30% of meeting time spent just explaining logic to the Frontend team.
Common Alternatives
Before switching entirely to Scalar, I considered a few popular alternatives:
- Redoc: Professional interface with a well-organized left-hand menu. However, the free version doesn’t allow direct API testing in the browser.
- Stoplight Elements: Modern but quite heavy to configure for medium and small Express.js projects.
- Postman/Insomnia: These are standalone tools. You have to export files and send them manually to colleagues, leading to version mismatches between code and documentation.
Scalar – A Breath of Fresh Air for API Documentation
Scalar combines the beauty of Redoc with the utility of Postman. This library is lightweight, supports generating Code Snippets for over 15 programming languages, and integrates deeply into the Node.js ecosystem.
Step 1: Install the Library
If you are using Express.js, install the Scalar adapter package along with swagger-jsdoc to scan API definitions:
npm install @scalar/express-api-reference swagger-jsdocStep 2: Configure the OpenAPI Specification
In the app.js file, define the basic API information as follows:
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: {
title: 'Node.js API Project',
version: '1.0.0',
description: 'API Documentation using Scalar',
},
servers: [{ url: 'http://localhost:3000' }],
},
apis: ['./routes/*.js'],
};
const specs = swaggerJsdoc(swaggerOptions);Step 3: Integrate Scalar Middleware
Instead of using swagger-ui-express, just replace it with Scalar using a few simple lines of code:
const express = require('express');
const { apiReference } = require('@scalar/express-api-reference');
const app = express();
app.use(
'/docs',
apiReference({
spec: { content: specs },
}),
);
app.listen(3000, () => {
console.log('API Documentation at: http://localhost:3000/docs');
});Real-World Experience After 6 Months
The most valuable feature of Scalar is the Integrated API Client. When you open an endpoint, the right-hand panel displays a request simulator identical to Postman. You can select languages like Node.js, Python, or Go to copy sample code for immediate use.
Customize Themes in a Heartbeat
Scalar allows you to change themes with just one line of configuration. If you like GitHub or Solarized styles, simply add the theme property:
apiReference({
theme: 'purple', // Options: 'default', 'moon', 'purple', 'solarized'
spec: { content: specs },
})High-Speed Search with Shortcuts
The Ctrl + K shortcut is a lifesaver for large projects. It opens a global search bar, allowing you to jump straight to the endpoint you need without endless scrolling.
A Few Practical Notes
To be honest, when I first switched to Scalar, I encountered display bugs with deeply nested objects. However, the development team handles GitHub issues very quickly, often releasing patches within the week.
If you use NestJS, Scalar also has a smooth built-in integration. Don’t forget to configure securitySchemes so Scalar displays the Bearer Token input field professionally.
In summary, if you’re tired of the outdated Swagger UI interface, Scalar is the most worthwhile upgrade today. It doesn’t just beautify your documentation; it actually improves the workflow speed for the entire team.
