Generating and Serving OpenAPI Docs: @umijs/openapi vs swagger-jsdoc vs swagger-ui-express

These three packages all relate to OpenAPI documentation, but they solve very different problems in the development workflow. Confusing them leads to architectural mismatches — like trying to serve a UI from a frontend bundle or generate client code from JSDoc alone. Let’s clarify what each does, how they’re used, and where they fit.

🧩 Core Purpose: What Problem Does Each Solve?

@umijs/openapi takes an existing OpenAPI spec and generates TypeScript code for frontend consumption.

// Example: openapi.config.ts
import { defineConfig } from '@umijs/openapi';

export default defineConfig({
  schemaPath: 'http://localhost:8080/v3/api-docs', // or local ./openapi.json
  serversPath: './src/services',
});

// After running `umi openapi`, you get:
// src/services/user.ts
export async function getUser(id: number): Promise<User> {
  return request(`/users/${id}`, { method: 'GET' });
}

swagger-jsdoc takes JSDoc comments in your source code and builds an OpenAPI spec.

// Example: routes/users.js
/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Get user by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: A user object
 */
app.get('/users/:id', (req, res) => {
  // ...
});

// Build script
const swaggerJsdoc = require('swagger-jsdoc');
const options = { definition: { /*...*/ }, apis: ['./routes/*.js'] };
const openapiSpec = swaggerJsdoc(options);
// Writes openapi.json

swagger-ui-express takes an OpenAPI spec and serves an interactive HTML UI via Express.

// Example: server.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./openapi.json');

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
// Now visit http://localhost:3000/api-docs

💡 Key insight: These tools are often used together, not as alternatives. For example: swagger-jsdoc → generates spec → swagger-ui-express serves it → @umijs/openapi consumes it to generate frontend code.

🔄 Workflow Integration: Where Do They Fit?

Backend-First Spec Authoring

If your team writes APIs first and documents them inline:

1. Use swagger-jsdoc to extract specs from JSDoc.
2. Feed that spec into swagger-ui-express to expose docs.
3. Share the generated openapi.json with frontend teams.
4. Frontend uses @umijs/openapi to generate typed services.

Contract-First Development

If you start with a hand-written OpenAPI spec (e.g., in openapi.yaml):

1. Backend implements routes to match the contract.
2. Use swagger-ui-express to serve the static spec.
3. Frontend runs @umijs/openapi directly against the YAML file.
4. Skip swagger-jsdoc entirely.

⚙️ Configuration and Output Differences

Input Requirements

• @umijs/openapi: Requires a valid OpenAPI 3.0+ document (URL or local file). Fails if spec is invalid.
• swagger-jsdoc: Requires JSDoc blocks tagged with @swagger and a config object defining API paths. Outputs a JSON spec.
• swagger-ui-express: Requires a JavaScript object or JSON representing the spec. No validation — garbage in, broken UI out.

Output Type

• @umijs/openapi: Produces TypeScript files with fetch wrappers or React hooks.
• swagger-jsdoc: Produces a single OpenAPI JSON object.
• swagger-ui-express: Produces HTML, CSS, and JS assets served dynamically by Express.

🌐 Runtime vs Build-Time

@umijs/openapi runs at build time (or manually via CLI). It’s a code generator, not a runtime library. The output is plain .ts files committed to source control.

// package.json script
"scripts": {
  "gen:api": "umi openapi"
}

swagger-jsdoc also runs at build time or during server startup. Often integrated into CI or dev scripts to keep openapi.json up to date.

// During server init
const specs = swaggerJsdoc(options);
fs.writeFileSync('openapi.json', JSON.stringify(specs));

swagger-ui-express runs at runtime inside an Express server. It’s middleware that responds to HTTP requests with the Swagger UI.

// Only active when server is running
app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec));

🛑 Common Misuses to Avoid

• Don’t use swagger-ui-express in a Create React App or Vite project. It needs Node.js and Express — it won’t work in the browser.
• Don’t expect @umijs/openapi to parse JSDoc. It only reads OpenAPI specs, not source code comments.
• Don’t feed raw JSDoc to swagger-ui-express. It needs a fully formed spec object, which swagger-jsdoc can provide.

🔁 Real Integration Example

Here’s how they work together in a full-stack project:

Step 1: Backend uses swagger-jsdoc

// src/routes/user.js
/**
 * @swagger
 * /api/v1/users:
 *   get:
 *     summary: List all users
 *     responses:
 *       200:
 *         description: User list
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
router.get('/users', controller.list);

Step 2: Generate and serve spec

// src/server.js
const swaggerSpec = swaggerJsdoc({
  definition: { openapi: '3.0.0', info: { title: 'API' } },
  apis: ['./src/routes/*.js']
});

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
// Also write to disk for frontend
fs.writeFileSync('./public/openapi.json', JSON.stringify(swaggerSpec));

Step 3: Frontend generates clients with @umijs/openapi

// openapi.config.ts
export default defineConfig({
  schemaPath: './public/openapi.json',
  serversPath: './src/api',
  mockFolder: './mocks',
});

// Run: npx umi openapi
// Output: ./src/api/user.ts with typed functions

Now frontend devs import getUser() with full TypeScript support, while backend docs stay live at /api-docs.

📊 Summary: When to Use Which

💡 Final Recommendation

These tools aren’t competitors — they’re complementary pieces of an API documentation pipeline. Choose based on your role:

• Frontend engineers: Reach for @umijs/openapi to consume specs.
• Backend engineers: Use swagger-jsdoc to author specs and swagger-ui-express to publish them.
• Full-stack teams: Combine all three for a seamless contract-driven workflow.

Avoid forcing one tool to do another’s job. Keep the concerns separate: spec authoring, spec serving, and client generation. That’s how you get reliable, maintainable API integrations.