Docbagel

Docbagel is a CLI tool to generate JSDoc for you API routes, enabling easy to use & interactive SwaggerUI with OpenAPI specs.

PS: I initially intended it to work with Express & Node. Extending it to work with other frameworks is possible.

Prerequisites

• Node.js 20 or newer

Installation

npm install -g docbagel

Provide your Gemini API key through GEMINI_API_KEY (or pass --set-api-key when invoking the CLI)

docbagel --set-api-key "your-gemini-api-key"
# or
npx docbagel --set-api-key "your-gemini-api-key"

Automatically setup config file for your tool, config available at user/<username>/.docbagel/config.

Project setup

• Project Structure

/src
  index.js
  /controllers
    /user.controller(.js/.ts) # Where core business logic exists with API response structures and error handling
  /routers
    /user.router(.js/.ts) # Where routes are defined with route params, HTTP methods and middlewares.

• SwaggerUI setup

npm i swagger-jsdoc swagger-ui-express

• Config file swagger.js

import swaggerJSDoc from "swagger-jsdoc";
import { config } from "dotenv";
config();

const protocol = process.env.NODE_ENV === "production" ? "https" : "http";
const port = process.env.PORT || 3000;
const host = process.env.API_BASE_URL || `${protocol}://localhost:${port}`;

const definition = {
  openapi: "3.0.0",
  info: {
    title: "Video Backend API",
    version: "1.0.0",
    description: "API documentation for Video backend",
  },
  servers: [
    {
      url: host,
      description:
        process.env.NODE_ENV === "production"
          ? "Production server"
          : "Local server",
    },
  ],
};

const options = {
  definition,
  apis: ["./src/routes/*.js", "./src/controllers/*.js", "./src/models/*.js"],
};

export const swaggerSpec = swaggerJSDoc(options);

• Configure app.js

import express from "express";
import { swaggerSpec } from "./utils/swagger.js";
import swaggerUi from "swagger-ui-express";

const app = express();

app.get("/api-docs.json", (req, res) => {
  const baseUrl =
    process.env.API_BASE_URL || `${req.protocol}://${req.get("host")}`;
  const spec = { ...swaggerSpec, servers: [{ url: baseUrl }] };
  res.setHeader("Content-Type", "application/json");
  res.send(spec);
});

app.use(
  "/api-docs",
  swaggerUi.serve,
  swaggerUi.setup(undefined, {
    swaggerOptions: { url: "/api-docs.json" },
  })
);
app.listen(3000, () => {
  console.log(`App running a port 3000`);
});

Usage

Generate an OpenAPI spec from one or more local documents (supply multiple paths after -u) & output into a file where your routes are defined (using the flag -o):

_ Make sure the files already exist otherwise it will start creating new files with the content _

cd src
npx docbagel -u index.js controllers/user.controller.js -o routers/user.route.js

You can fine-tune the run with flags:

• -i, --instructions – add high-level requirements for the spec output
• -m, --model – override the Gemini model (default: gemini-1.5-pro-latest)
• --chunk-size / --chunk-overlap – control text splitting before calling Gemini
• -k, --api-key – supply the API key explicitly instead of the environment variable

You may need to make to make some minor fixes manually for missing brackets or comments

Make sure to add JSDoc for each respective route seprately above the code where the route is defined

Example

/**
 * @openapi
 * /api/v1/user/{id}:
 *   get:
 *     summary: Get User by ID
 *     tags: [User]
 *     responses:
 *       200:
 *         description: Return an User object using ID
 */
router.get("/user/[:id]", getUserById);
/**
 * @openapi
 * /api/v1/user/{name}:
 *   get:
 *     summary: Get User by name
 *     tags: [User]
 *     responses:
 *       200:
 *         description: Return an User object using name
 */
router.get("/user/[:name]", getUserByName);