Skip to main content

Swagger Integration

Swagger, an open-source framework, supported by an extensive ecosystem of tools, facilitates the design, build, documentation, and consumption of RESTful Web services.

FortJs simplifies Swagger integration with its dedicated library - fortjs-swagger, enabling automatic generation of Swagger documents.

Install library

npm install fortjs-swagger


Initiate the Swagger after the FortJs has started.

import * as path from "path";
import { Fort } from "fortjs";
import { routes } from "@/routes";
import { swagger } from "fortjs-swagger";

const swaggerPath = path.join(__dirname, "../dist/swagger/");
const initSwagger = async () => {
await swagger.create({
appInfo: {
title: "Swagger Test",
description: "Swagger Test",
version: "1.0"
servers: [{
description: "local",
url: "http://localhost:4000"
outputPath: swaggerPath,
securitySchemes: {
basicAuth: {
type: "http",
scheme: "basic"

export const createApp = async () => {
Fort.folders = [
alias: "/",
path: path.join(__dirname, "../static")
alias: "/swagger",
path: swaggerPath

Fort.routes = routes;
await initSwagger();
await Fort.create();
process.env.APP_URL = `http://localhost:${Fort.port}`;

createApp().then(() => {
Fort.logger.debug(`Your fort has been forged and is now ready for exploration at ${process.env.APP_URL}`);
}).catch(err => {

Start the server and navigate to the Swagger documentation path, which is http://localhost:4000/swagger/

You will see the available endpoints listed; however, documentation is currently absent. To enable proper Swagger configuration, we need to document each endpoint with relevant information.

Document API's

Fort.js includes special decorators for specifying the structure of your API endpoints. These decorators are:

  • summary: Provides a brief description of the endpoint.
  • response: Defines the expected structure of the response.
  • param: Specifies parameters in the request path.
  • query: Defines parameters in the query string.
  • security: Defines security type of the end point.

Let's apply these decorators on UserController which deals with operations related to users -

import { Controller, textResult, jsonResult, HTTP_STATUS_CODE, validate, shields, http, singleton } from 'fortjs';
import { UserService } from '@/services/user_service';
import { User } from '@/models/user';
import { swagger } from 'fortjs-swagger';
import { AuthenticationShield } from '@/shields/authentication_shield';

export class UserController extends Controller {

service: UserService;

constructor(@singleton(UserService) userService: UserService) {
this.service = userService;

@swagger.summary('get all users')
@swagger.description('return all saved users')
@swagger.response(HTTP_STATUS_CODE.Ok, [User])
@swagger.query("offset", 1, "offset")
@swagger.query("limit", 10, "no of records in the response")
async getUsers() {
const { offset, limit } = this.query;
return jsonResult(this.service.getUsers());

@swagger.summary('Add user')
@swagger.response(HTTP_STATUS_CODE.Created, User)
@swagger.body(User, "User model")"/")
async addUser() {
const user = this.body as User;
const newUser = this.service.addUser(user);
return jsonResult(newUser, HTTP_STATUS_CODE.Created);

@swagger.summary('get a single user by id')
@swagger.response(HTTP_STATUS_CODE.Ok, User)
@swagger.response(HTTP_STATUS_CODE.NotFound, 'invalid user')
@swagger.param('id', 1, 'user id')
async getUser() {
const userId = Number(;
const user = this.service.getUser(userId);
if (user == null) {
return textResult("invalid user id", HTTP_STATUS_CODE.NotFound);
return jsonResult(user);


In the above snippet we have used swagger helpers decorators to document the API's structure. Now refresh the Swagger URL (http://localhost:4000/swagger/). You will now observe all the APIs with comprehensive documentation.


Note: Certain decorators, such as response, query, etc., can be applied multiple times to represent various scenarios, providing a more thorough overview of the API's capabilities.

More resources