Package Exports

express-swagger-autogen
express-swagger-autogen/dist/autogen.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (express-swagger-autogen) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

express-swagger-autogen

A library that auto generates swagger docs to your endpoints from express.

Installation

npm install express zod express-swagger-autogen

You must set these configs in your tsconfig.json:

"emitDecoratorMetadata": true,
"experimentalDecorators": true,

Usage

You must use the Router instance from express.
The autogen must be executed in the end your router stack.

For example:

import express from "express";
import expressSwaggerAutogen from "express-swagger-autogen";

const router = express.Router();

router.get("/healthcheck", controller);
router.get("/user/:id", controller);
// others routes ...

expressSwaggerAutogen(router);
// Then the autogen will generate documentation for your endpoints also with path parameters.

const app = express();
app.use(router);
app.listen(3000, () => console.log("Server is running on http://localhost:3000"));

You may set some configurations as the second parameter of the autogen:

You own setup object:

const config = {
  setup: {
    openapi: "3.0.0",
    info: {
      title: "API Name" || process.env.npm_package_name,
      version: "1.0.0" || process.env.npm_package_version,
    },
  },
};

expressSwaggerAutogen(router, config);

You also may detail your endpoint documentation using the Documentation decorator:

import express, { Request, Response } from "express";
import z from "zod";
import expressSwaggerAutogen, { Documentation, StatusCodes } from "express-swagger-autogen";

const router = express.Router();

/* You may validate the schema inside your handler */
const LoginSchema = z.object({
  email: z.email("Invalid email"),
  password: z.string().min(1, "Password is required"),
});

abstract class UserController {
  @Documentation({
    summary: "User login",
    description: "Endpoint for user login",
    zod: {
      requestBody: LoginSchema,
      responses: {
        [StatusCodes.OK]: z.void().describe("User logged in successfully"),
        [StatusCodes.BAD_REQUEST]: z.object({
          message: z.string().describe("Message describing the error").meta({
            example: "Invalid email",
          }),
        }),
        [StatusCodes.UNAUTHORIZED]: z.void().describe("Invalid credentials"),
      },
    },
  })
  static login(req: Request, res: Response) {
    const parsed = LoginSchema.safeParse(req.body);

    if (!parsed.success) {
      return res.status(StatusCodes.BAD_REQUEST).json({ message: parsed.error.message });
    }

    const { email, password } = parsed.data;

    /*
    const user = repository.getUser(email, password);
    if (!user) {
        return res.status(StatusCodes.UNAUTHORIZED);
    }
    */

    return res.status(StatusCodes.OK);
  }
}

router.post("/user/login", UserController.login);

expressSwaggerAutogen(router);

const app = express();
app.use(router);
app.listen(3000, () => console.log("Server is running on http://localhost:3000"));

See some examples here about how to use.

License

MIT