Implementing API Documentation

npm i swagger-ui-express swagger-jsdoc

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      responses:
        "200": { description: OK }

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: User
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "404": { description: Not found }

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:    { type: integer, example: 42 }
        email: { type: string, format: email }
        role:  { type: string, enum: [admin, user] }

import swaggerUi from "swagger-ui-express";
import openapi from "./openapi.json" with { type: "json" };
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(openapi));

import swaggerJSDoc from "swagger-jsdoc";

/**
 * @openapi
 * /users:
 *   get:
 *     summary: List users
 *     responses:
 *       200: { description: OK }
 */
app.get("/users", listUsers);

const spec = swaggerJSDoc({
  definition: { openapi: "3.1.0", info: { title: "API", version: "1.0.0" } },
  apis: ["./src/routes/*.js"]
});

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

import { OpenApiGeneratorV31, OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
const registry = new OpenAPIRegistry();
registry.registerPath({ method: "get", path: "/users", responses: { 200: { description: "OK" } } });
const spec = new OpenApiGeneratorV31(registry.definitions).generateDocument({
  openapi: "3.1.0", info: { title: "API", version: "1.0.0" }
});

app.use("/api-docs/v1", swaggerUi.serveFiles(specV1, {}), swaggerUi.setup(specV1));
app.use("/api-docs/v2", swaggerUi.serveFiles(specV2, {}), swaggerUi.setup(specV2));