Self documented, self validated, typescript-first router for express
Allows you to define your routes and endpoints in a typescript-first way, with automatic input validation and OpenAPI documentation generation.
Returns an express app with the routes and endpoints defined, plus a swagger UI documentation endpoint. This app can be later extended with more routes, middlewares, error middlewares or started with app.listen().
- Automatic input validation with Zod
- Automatic OpenAPI extension with Zod
- Type safe input and output
- Auto generated documentation
Install the package:
npm install @expresso/routerExpresso router's main function is the createEndpoint function. This function is responsible for building the OpenAPI metadata that will be later used to generate the swagger ui documentation.
When creating an endpoint, you need to describe its input, output and give it at least one handler.
The input property is an object containing a body, params and / or query properties, each being a Zod schema. If your request has no inputs you can omit this property. The corresponding req properties will be validated and transformed using these schemas. You can also specify a headers property, which should contain a map of <string, HeaderObject> according to OpenAPI spefication. These headers will not be automatically validaded for now
The output property is an object literal having one property for each possible status code for that endpoint. Each status code receives a body property, which is the Zod schema describing the body of that response. Optionally, each status code can also have a headers property, containing the Response headers for that status code. The res.status().json() typing will ensure that you use the correct body for the status you choose.
The handlers property is a function or array of optionally async functions. Errors and async errors are automatically captured and fed to next, so the express error handling flow works as normal.
Besides the input, output and handlers properties. All other OpenAPI properties for an endpoint are supported, but optional. We recommend using the tags property to group this endpoint with other similar ones and the description property to add a little bit of context to your endpoints. If you don't specify a tags property, the endpoint will be grouped with the default tag "default".
You can see more about the OpenAPI specification at https://swagger.io/.
import crypto from 'crypto';
import { createEndpoint, z } from '@expresso/router';
type User = { id: string; name: string; email: string; password: string }
const USERS: User[] = []
const createUser = createEndpoint({
description: 'If you call this and a user already exists, it will be shit',
summary: 'Create a new user',
tags: ['Usuários'],
input: {
body: z.object({
name: z.string().min(1),
email: z.string().email().min(1),
password: z.string().min(16)
}),
query: z.object({
testNumber: z
.string()
.refine((s) => !Number.isNaN(Number(s)))
.transform((n) => parseInt(n, 10))
.optional()
}),
headers: {
authorization: {
description: 'Authorization token'
}
}
},
output: {
201: {
body: z.object({
id: z.string().min(1),
name: z.string().min(1),
email: z.string().email().min(1)
}),
headers: {
'x-content-range': {
description: 'Describes a content range'
}
}
},
409: {
body: z.object({
status: z.literal(409),
message: z.string().min(1)
})
}
},
handlers: [
(_req, _res, next) => {
next()
},
(req, res) => {
const { name, email, password } = req.body
const id = crypto.randomBytes(16).toString('hex')
USERS.push({
id,
name,
email,
password
})
res.status(201).json({
id,
name,
email
})
}
]
})Each endpoint object allows you to pass a single error handler function, this function is an Express error handling middleware with the signature (err: any, req: Request, res: Response, next: NextFunction) => void.
This object is optional and can be passed as the errorHandler property of the endpoint object. If you pass it, the error handler will be concatenated in the end of the handlers array, so it will be called after all other handlers in case there's an error.
import crypto from 'crypto';
import { createEndpoint, z } from '@expresso/router';
type User = { id: string; name: string; email: string; password: string }
const USERS: User[] = []
const createUser = createEndpoint({
// ... All the previous openapi properties
handlers: [
(_req, _res, next) => {
next()
},
(req, res) => {
const { name, email, password } = req.body
if (checkEmailExists(email)) {
next(new UserError('Email already exists'))
return
}
const id = crypto.randomBytes(16).toString('hex')
USERS.push({
id,
name,
email,
password
})
res.status(201).json({
id,
name,
email
})
}
],
errorHandler: (err, _req, res) => {
if (err instanceof UserError) {
return res.status(409).json({
status: 409,
message: err.message
})
}
}
})Note: The error handler passed to this property will only be available to this particular endpoint, if you want to create a global error handler, you can either use the app.use function after the createApp function, or you can refer to the global error handling section.
It will only return a 422 status code with the validation issues if the error is an instance of ZodError (which means it will only capture validation errors), otherwise it will call next(err) allowing you to chain more handlers in the end of the middleware chain.
The router also exports an extension of the Zod lib with an extra method, openapi. This method is used to add OpenAPI metadata to the schema, which will be used to generate the swagger documentation. The openapi method receives an object with the OpenAPI properties you want to add to the schema.
This feature uses the underlying extendZodWithOpenApi function from the @anatine/zod-openapi package. If you want to import your own Zod function, this is also possible, just make sure to use the extendZodWithOpenApi function from the same package.
import crypto from 'crypto';
import { createEndpoint, z } from '@expresso/router';
type User = { id: string; name: string; email: string; password: string }
const USERS: User[] = []
const createUser = createEndpoint({
description: 'If you call this and a user already exists, it will be shit',
summary: 'Create a new user',
tags: ['Usuários'],
input: {
body: z.object({
name: z.string().min(1).openapi({ description: 'This is the username', example: 'JohnDoe' }),
email: z.string().email().min(1),
password: z.string().min(16)
}),
query: z.object({
testNumber: z
.string()
.refine((s) => !Number.isNaN(Number(s)))
.transform((n) => parseInt(n, 10))
.optional()
.openapi({ default: 100 })
}),
headers