Solution that generates beatiful Swagger API documentation from code. 💻

It lists all of endpoints registred within app with their routes, methods, relevant middlewares.

When it comes to generating 📑Swagger documentation, you have two options. Generate Swagger UI that can be served as a static file within your application, or keep documentation as data.json file within defined 📁location.

For more information see Config parameters bellow ⬇.

This simple tool does not require you to write any more code that necessary. Documentation is generated from source code itself without using annotations or separate doc files.

Use the package manager (npm or yarn) to install dependencies.

npm install @goodrequest/express-joi-to-swagger
or
yarn add @goodrequest/express-joi-to-swagger

✖ This solution is suitable for everybody who uses Express in a combination with Joi to build application's API. This version was developed and tested on versions 17.x.x of Joi. For version 14.x.x we have parallel branch v14. For proper functioning it is also necessary to use Typescipt version 3.7.5 and higher.

✖ As mentioned before, it is not needed to use annotations in your code, however to make this tool works properly you need to obey some coding practices. You need define at least one router in your application. If you want to include request and response Joi schemas in a documentation they need to be named the same and exported.

✖ If you are using middleware for user authorization and wish to include endpoint permissions in the documentation as well you need to name the function responsible for handling this and provide permissions array as its input parameter.

You can find simple examples of all mentioned in the demo folder of this repository. Quick usage example can also be found below ⬇.

// imports
import getSwagger from '@goodrequest/express-joi-to-swagger'
import path from 'path'
import app from './your-path-to-express-app'

// Config example
const config: IConfig = {
	outputPath: path.join(__dirname, 'dist'),
	generateUI: true,
	permissions: {
		middlewareName: 'permission',
		closure: 'permissionMiddleware',
		paramName: 'allowPermissions'
	},
	requestSchemaName: 'requestSchema',
	responseSchemaName: 'responseSchema',
	businessLogicName: 'businessLogic',
	swaggerInitInfo: {
		info: {
			description: 'Generated Store',
			title: 'Test app'
		}
	},
	tags: {}
}

// Use case example
function workflow() {
	getSwagger(app, config).then(() => {
		console.log('DONE')
	}).catch((e) => {
		console.log('ERROR', e)
	})
}

// Start script
workflow()

Middlewares and router implementation.

router.get(
		'/users/:userID',
		
		// permissionMiddleware
		permissionMiddleware(['SUPERADMIN', 'TEST']),
		
		validationMiddleware(requestSchema),
		
		// businessLogic
		businessLogic
	)

//permissions middleware impelemntation
export const permissionMiddleware = (allowPermissions: string[]) => function permission(req: Request, res: Response, next: NextFunction) {
	...
}

Generated SwaggerUI

Swagger bug reports shows inconsistency error in the schema and/or your route definition.

1. In this case the default value is not present in valid values.

orderBy: Joi.string().lowercase()
.valid('name', 'duration', 'calories', 'views')
.empty(['', null]).default('order'),

2. If you defined id as parameter within route but forgot to define it the schema Swagger will report error.

//route with id as parameter

router.put('/:id',

schema definition

//joi schema that does not include definition for id param

params: Joi.object()

Any 👐 contributions, 🐛 issues and 🌟 feature requests are welcome!

Feel free to check following #TODO ideas we have:

• Express endpoint parser to retrieve a list of the passed router with the set verbs.
• Conversion library for transforming Joi schema objects into Swagger schema definitions.
• A simple tool that help you to retrieve the function location from its reference.