z-openapi

z-openapi can help you create swagger definition.

From a Zopenapi instance, each component and subcomponent are fluents. You can describe them either with a plain javascript object, either with a factory function who takes and returns a fluent builder instance. Some components have helpers functions to help saving time.

eg: <Schema instance>.string(true) for <Schema instance>.type('string').required(true)

Typescript hint enabled ! Yeay ! Let's dive into it !

In a Node project install z-openapi

$ npm install --save z-openapi

At some point in your code, import Zopenapi class, and export an instance for other modules to enhance it.

import { Zopenapi } from 'z-openapi';
export const zoa = new Zopenapi();

Describe top level informations

zoa
	.info(info => info // this is the builder instance
		.title('Swagger title')
		.version('1.0.0')
		.description('Swagger description')
		
		// Same for each compnt / subcompnt:
		
		// Equivalent
		// .license({ name: 'ISC' }) // plain openapi object
		.license(license => license.name('ISC')) // factory function
		
		.contact(contact => contact
			.name('Swagger contact name')
			.email('Swagger contact email')
			.url('Swagger contact url')
		)
	)
	.servers(
		{ url: 'http://localhost:3000' },
		{ url: 'https://another-hostname.com' },
	)
	.components(components => components
		.schemas({
			BaseError: baseError => baseError.object({
				name: name => name.string(true).description('Swagger schema description'),
				message: message => message.string(true),
			}).description('Swagger schema description'),
		})
		  
		.securitySchemes({
			bearer: bearer => bearer.name('Authorization').in('header'),
			apikey: apikey => apikey.name('api-key').in('query'),
		})
		.
	);
	
/*
.
.
.
*/

Add more schemas in your model's modules

	zoa.componentsSchemas({
		  
		User: user => user.object({
			id: id => id.string(),
			email: email => email.string(true),
			password: password => password.string(),
		}),

		Users: users => users.array(items => items.ref('User')),
			
		CreateUser: user => user.object({
			email: email => email.string(true),
			password: password => password.string(true),
		}),

		UpdateUser: user => user.object({
			email: email => email.string(),
			password: password => password.string(),
		})
	});

Add paths in your router's modules

zoa.paths({

	'/users': path => path
		.get(get => get
			.response200(resp => resp.jsonSchema(json => json.ref('Users')))
			.security({ bearer: [] })
		)
		.post(post => post
			.requestBody(body => body.jsonSchema(json => json.ref('CreateUser')))
			.response200(resp => resp.jsonSchema(json => json.ref('User')))
			.security({ apikey: [] })
		),

	'/users/{id}': path => path
		.get(get => get
			.parameters(param => param.name('id'))
			.response200(resp => resp.jsonSchema(json => json.ref('User')))
			.security({ bearer: [] })
		)
		.put(put => put
			.parameters(param => param.name('id'))
			.requestBody(body => body.jsonSchema(json => json.ref('UpdateUser')))
			.response200(resp => resp.jsonSchema(json => json.ref('User')))
			.security({ bearer: [] })
		)
		.delete(del => del
			.parameters(param => param.name('id'))
			.response200(resp => resp.jsonSchema(json => json.ref('User')))
			.security({ bearer: [] })
		)
});

Finnaly, to get it serve by swagger-ui

import swaggerUi from 'swagger-ui-express';
	
/*
.
.
.
*/

app.use('/docs',  swaggerUi.serve,  swaggerUi.setup(zoa.js()));