swagger-less

🧼 A clean, programmatic way to define Swagger/OpenAPI documentation for Express.js routes — no JSDoc comments, no YAML, no clutter.

---

✨ Features

• ✅ Programmatic Swagger config attached directly to your Express routes
• 🚫 No JSDoc comments needed
• 🔁 Reusable, composable structure
• 📄 Automatically supports route parameters, request bodies, and responses
• 🔐 Supports .security() for JWT/API key-based auth
• 🛑 Supports .deprecated() flagging
• 🔎 Clean and intuitive chaining API

---

📦 Installation

1npm install swagger-less

---

🧠 Concept

Instead of cluttering your codebase with verbose Swagger comments or YAML files, swagger-less lets you define documentation using a fluent builder API:

1swaggerless('post', '/api/user/login')
2  .summary('Login user')
3  .description('Authenticates a user and returns a JWT')
4  .tag('Authentication')
5  .body({ email: 'string', password: 'string' }, { description: 'User credentials' })
6  .response(200, { token: 'string' }, 'Login successful')
7  .build()

---

🚀 Basic Usage

1. Define Routes with Swagger Metadata

1 
2const { swaggerless } = require('swagger-less');
3const router = express.Router();
4 
5router.post(
6  '/login',
7  swaggerless('post', '/api/auth/login')
8    .summary('User login')
9    .description('Log in a user and return a JWT')
10    .tag('Auth')
11    .body({ email: 'string', password: 'string' })
12    .response(200, { token: 'string' }, 'Login successful')
13    .response(401, null, 'Invalid credentials')
14    .security([{ bearerAuth: [] }])
15    .build(),
16  controller.login
17);
18
19module.exports = router;

---

2. Set Up Global Swagger Metadata in main.js

1const express = require('express');
2const swaggerUi = require('swagger-ui-express');
3const { configure, generateSpec } = require('swagger-less');
4const routes = require('./routes');
5
6const app = express();
7
8// ✅ Global Swagger metadata setup
9configure({
10  openapi: '3.0.0',
11  info: {
12    title: 'Your API',
13    version: '1.0.0',
14    description: 'Auto-generated Swagger docs from swagger-less',
15  },
16  servers: [
17    { url: 'http://localhost:3000', description: 'Local dev' }
18  ],
19  components: {
20    securitySchemes: {
21      bearerAuth: {
22        type: 'http',
23        scheme: 'bearer',
24        bearerFormat: 'JWT'
25      }
26    }
27  }
28});
29
30app.use(express.json());
31app.use('/api', routes);
32
33// 📄 Serve Swagger UI
34app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(generateSpec()));
35
36app.listen(3000, () => console.log('Server running on port 3000'));

---

🧱 Full Builder API

Method	Description
.summary(text)	Summary of the endpoint
.description(text)	Full description
.tag(name)	Tag for grouping endpoints
.param(location, name, options)	Define query/path/header param
.body(schema, options)	Define request body with type object
.response(code, schema, description)	Add a response
.deprecated()	Mark route as deprecated
.security(schemes)	Add security (e.g., JWT bearerAuth)
.build()	Finalize and register the route

---

🔧 Param Examples

1.param('query', 'limit', { type: 'integer', required: false, description: 'Number of items' })
2.param('path', 'id', { type: 'string', required: true, description: 'Resource ID' })

---

🔐 Security Example

Add .security() to your route:

1.security([{ bearerAuth: [] }])

And define the scheme globally using configure():

1configure({
2  components: {
3    securitySchemes: {
4      bearerAuth: {
5        type: 'http',
6        scheme: 'bearer',
7        bearerFormat: 'JWT'
8      }
9    }
10  }
11});

---

♻ Reusable Route Template Example

You can define reusable builder templates:

1// shared/swaggerTemplates.js
2const { swaggerless } = require('swagger-less');
3
4function authPostRoute(path, summary, bodySchema, responses = {}) {
5  const builder = swaggerless('post', path)
6    .summary(summary)
7    .tag('Auth')
8    .body(bodySchema)
9    .security([{ bearerAuth: [] }]);
10
11  for (const [code, desc] of Object.entries(responses)) {
12    builder.response(parseInt(code), null, desc);
13  }
14
15  return builder;
16}
17
18module.exports = { authPostRoute };

Use it in your route files:

1// routes.js
2const { authPostRoute } = require('./shared/swaggerTemplates');
3
4router.post(
5  '/refresh',
6  authPostRoute('/api/auth/refresh', 'Refresh JWT', { token: 'string' }, {
7    200: 'Token refreshed',
8    401: 'Invalid token'
9  }).build(),
10  controller.refreshToken
11);

---

🧹 CLI (Legacy/Optional)

A deprecated CLI exists for static comment injection, though swagger-less now works at runtime with configure() + generateSpec():

1npx swagger-less -i ./src/routes.js -o ./src/routes.injected.js

Not recommended unless you're generating static documentation for legacy reasons.

---

📄 License

MIT © Code-Hashira

---