View as Json

Swagger API Documentation

The Swagger API Documentation component provides an automated way to generate and serve interactive API documentation.

Installation

Install the component using the servercn CLI:

npx servercn-cli add swagger-docs

Implementation Guide

Configuration

The configuration file defines the metadata for your API and where Swagger should look for documentation comments.

src/swagger.config.ts
import swaggerAutoGen from "swagger-autogen";
 
const doc = {
  info: {
    title: "Stateless Auth API",
    description: "Stateless Auth API",
    version: "1.0.0"
  },
  host: "localhost:8000",
  schemes: ["http"]
};
 
const outputFile = "./docs/express/swagger.json"; // Output file for the generated docs
const endpointsFiles = ["./routes/*.ts"]; // Endpoints files to be parsed
 
swaggerAutoGen(outputFile, endpointsFiles, doc);

Run the Script

Run the script to generate the swagger.json file.

node src/swagger.config.ts

It will generate a swagger.json file in the docs directory.

Setup Swagger

Create a swagger.ts file in the src/configs directory.

src/configs/swagger.ts
import swaggerUi from "swagger-ui-express";
import { Express } from "express";
 
import swaggerDocument from "../docs/express/swagger.json"; // Generated by swagger-autogen by running `node src/swagger.config.ts`
 
export const setupSwagger = (app: Express) => {
  app.use("/api/docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));
};

Integration with App

Update your main app.ts to initialize the Swagger documentation.

src/app.ts
import express from "express";
import { setupSwagger } from "./configs/swagger";
 
const app = express();
 
// Initialize Swagger
setupSwagger(app);
 
app.listen(8000, () => {
  console.log("Server started on port 8000");
  console.log("Swagger docs available at http://localhost:8000/api/docs");
});

Update swagger.json file (Optional)

Update the swagger.json file with the new API documentation.

Accessing the Docs

Once your server is running, navigate to:

http://localhost:8000/api/docs

You will see the Swagger UI dashboard where you can explore and test your API.

Don't forget to run `node src/swagger.config.ts` command and update the base url, routes... in `swagger.json` file.

File & Folder Structure

Loading files...

Installation

npx servercn-cli add swagger-docs