Package Exports

tspace-swagger-ui-express
tspace-swagger-ui-express/build/lib/index.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 (tspace-swagger-ui-express) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

tspace-swagger-ui-express

tspace-swagger-ui-express is an auto-generated Swagger-UI API documentation tool for Express applications.

Install

Install with npm:

npm install tspace-swagger-ui-express --save

Setup

import express , { Request , Response , NextFunction } from 'express';
import swagger from 'tspace-swagger-ui-express';

(async() => { 

  const app = express()

  app.get("/", (req : Request, res : Response , next : NextFunction) => {
    return res.send("Hello, world!");
  });

   app.get("/:uuid", (req : Request, res : Response , next : NextFunction) => {
    return res.send(`Hello, world! with uuid : ${req.params.uuid}`);
  });

  app.use(swagger(app))
  
  const PORT = 3000;

  app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}/api/docs`);
  })
  
})()

Custom

Server

import express , { Request , Response , NextFunction } from 'express';
import swagger from 'tspace-swagger-ui-express';
import catRoute from './catRoute';
import CatController from './CatController';

(async() => { 

  const app = express()

  app.get("/", (req : Request, res : Response , next : NextFunction) => {
    return res.send("Hello, world!");
  });

  app.use("/api/v1/cats",catRoute)

  app.use(swagger(app , { 
    // customOnly : true, use only custom by @Swagger only
    path : "/api/docs",
    servers : [
      { url : "http://localhost:3000" , description : "development"}, 
      { url : "http://localhost:8000" , description : "production"}
    ],
    info : {
      "title" : "Welcome to the documentation of the 'cats' story",
      "description" : "This is the documentation description about around the 'cats' story"
    },
    excepts : [
      // if you want to excepts some path following the example
      
      // {
      //   path : /^\/api\/v\d+\//,
      //   method : ['GET','POST'],
      // }
      // /^\/api\/v\d+\/cats/,
      // /\/cats/
      //  "/api/v1/cats"
      // "/api/v1/cats/:uuid"
    ],
    controllers : [CatController] // For custom requests related to controllers with decorators such as @Swagger.
    // controllers : {
    //   folder : `${__dirname}/controllers`,
    //   name :  /controller\.(ts|js)$/i
    // } // if you want to use the directory for include all controllers
    responses : [
      {
        status: 200,
        description: "OK",
        example: {
            success: true,
            message: "Cats say 'OK, slave'😻"
        }
      },
      {
        status: 201,
        description: "Created",
        example: {
          success: true,
          message: "Cats say 'Welcome, new slave'😻"
        }
      },
      {
          status: 400,
          description: "Bad Request",
          example: {
            success: false,
            message: "Cats say 'Bad foods'😻"
          }
      },
      {
          status: 401,
          description: "Unauthorized",
          example: {
            success: false,
            message: "Cats say 'Give me the food first'😻"
          }
      },
      {
        status: 403,
        description: "Forbidden",
        example: {
          success: false,
          message: "Cats say 'Not your business, slave'😻"
        }
      },
      {
        status: 500,
        description: "Server Error",
        example: {
          success: false,
          message: "Cats can't say 'What's the curse'😻"
        }
      }
    ]
  }))
  
  const PORT = 3000;
  
  app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}/api/docs`);
  });
  
})()

Controller

import { Request , Response , NextFunction } from 'express';
import { Swagger } from 'tspace-swagger-ui-express';

class CatController {
  @Swagger({
    match : {
      path : "/v1/cats",
      method : 'GET',
    },
    query : {
      id: {
        type : 'string',
        required: true,
        description : "The 'id' of the cat"
      },
      name: {
        type : 'string',
      }
    },
    cookies : {
     names : ['id', 'name'],
     description : 'The cookies for every logged'
    },
    bearerToken : true,
    responses : [
      { status : 200 , description : "OK" , example : { id : 1 , name : 'catz' }},
      { status : 400 , description : "Bad request" , example : { message : "Bad Bad Bad food" }}
    ]
  })
  public index (req : Request , res : Response , next : NextFunction) {
    return res.json({ message : 'hello world' });
  }

  @Swagger({
    match : {
      path : "/v1/cats",
      method : 'POST',
    },
    bearerToken : true,
    body : {
      description : 'The description !',
      required : true,
      properties : {
        id : {
          type : 'number',
          example : 1
        },
        name :  {
          type : 'string',
          example : "xxxxx"
        }
      }
    }
  })
  public store (req : Request , res : Response , next : NextFunction) {
    return res.json({ message : req.params });
  }

  @Swagger({
    match : {
      path : "/v1/cats/:uuid",
      method : 'GET'
    },
    params : {
      uuid: {
        description : "The 'uuid' of the cat",
        example : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    },
     query : {
      id: {
        type : 'string',
        required: true,
        description : "The 'id' of the cat",
        example : '1'
      },
      name: {
        type : 'string',
      }
    },
    responses : [
      { status : 200 , description : "OK" , example : { id : 'catz' }},
      { status : 400 , description : "Bad request" , example : { id : 'catz' }}
    ]

  })
  public show (req : Request , res : Response , next : NextFunction) {
    return res.json({ params : req.params , query : req.query });
  }

  @Swagger({
    match : {
      path : "/v1/cats/:uuid",
      method : ['PUT' , 'PATCH']
    },
    bearerToken : true,
    body : {
      description : 'The description !',
      required : true,
      properties : {
        id : {
          type : 'number',
          example : 1
        },
        name :  {
          type : 'string',
          example : "xxxxx"
        }
      }
    }
  })
  public async update (req : Request , res : Response , next : NextFunction) {
    return res.json({ body : req.body})
  }

  @Swagger({
    match : {
      path : "/v1/cats/:uuid",
      method : 'DELETE'
    },
    bearerToken : true
  })
  public async delete(req : Request , res : Response , next : NextFunction) {
    return res.json({ params : req.params})
  }

  @Swagger({
    match : {
      path : "/v1/cats/upload",
      method : "POST"
    },
    bearerToken : true,
    files : {
      required : true,
      properties : {
        file : {
          type : 'array',
          items: {
            type:"file",
            format:"binary"
          }
        },
        name : {
          type : 'string'
        }
      }
    }
  })
  public async upload (req : Request , res : Response , next : NextFunction) {
    return res.json({ files : req.files })
  }
}

export {CatController }
export default CatController

Router

import { Router } from "express"
import { CatController } from "./CatController"
const catRouter = Router()
const catInstance = new CatController()

catRouter
.get('/' , catInstance.index)
.post('/' , catInstance.store)
.post('/upload' , catInstance.upload)
.get('/:uuid' , catInstance.show)
.put('/:uuid' , catInstance.update)
.patch('/:uuid' , catInstance.updated)
.delete('/:uuid' , catInstance.delete)

export { catRouter }
export default catRouter

YAML & JSON

import express , { Request , Response , NextFunction } from 'express'
import { swaggerYAML , swaggerJSON } from 'tspace-swagger-ui-express'
import fs from 'fs'

(async() => { 

  const doc = { 
    path : "/api/docs",
    servers : [
      { url : "http://localhost:3000" , description : "development"}, 
      { url : "http://localhost:8000" , description : "production"}
    ],
    info : {
      "title" : "Welcome to the documentation of the 'cats' story",
      "description" : "This is the documentation description about around the 'cats' story"
    }
  }

  const app = express()

  app.get("/", (req : Request, res : Response , next : NextFunction) => {
    return res.send("Hello, world!");
  })

  const yaml = swaggerYAML(app,doc)
  const json = swaggerJSON(app,doc)

  fs.writeFileSync('swagger.yaml', yaml, 'utf8')
  fs.writeFileSync('swagger.json', json, 'utf8')

  app.use(swagger(app , {
    use : 'swagger.json' // 'swagger.yaml'
    // excepts don't work with file .json and .yaml
  }))

  const PORT = 3000
  
  app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
  })
  
})()