fastify/fastify-response-validation

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 137 Commits
.github		.github
test		test
types		types
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
example.mjs		example.mjs
index.js		index.js
package.json		package.json

Repository files navigation

@fastify/response-validation

CI NPM version neostandard javascript style

A simple plugin that enables response validation for Fastify. The use of this plugin will slow down your overall performance, so we suggest using it only during development.

Install

npm i @fastify/response-validation

Usage

You just need to register the plugin and you will have response validation enabled:

import fastify from 'fastify'
const app = fastify()
await app.register(require('@fastify/response-validation'))
app.route({
 method: 'GET',
 path: '/',
 schema: {
 response: {
 '2xx': {
 type: 'object',
 properties: {
 answer: { type: 'number' }
 }
 }
 }
 },
 handler: async (req, reply) => {
 return { answer: '42' }
 }
})
app.inject({
 method: 'GET',
 path: '/'
}, (err, res) => {
 if (err) throw err
 console.log(res.payload)
})

Different content types responses are supported by @fastify/response-validation, @fastify/swagger, and fastify. Please use content for the response otherwise Fastify itself will fail to compile the schema:

{
 response: {
 200: {
 description: 'Description and all status-code based properties are working',
 content: {
 'application/json': {
 schema: {
 name: { type: 'string' },
 image: { type: 'string' },
 address: { type: 'string' }
 }
 },
 'application/vnd.v1+json': {
 schema: {
 fullName: { type: 'string' },
 phone: { type: 'string' }
 }
 }
 }
 }
 }
}

If you want to override the default ajv configuration, you can do that by using the ajv option:

// Default configuration:
// coerceTypes: false
// useDefaults: true
// removeAdditional: true
// allErrors: true
import responseValidator from '@fastify/response-validation'
// ... App setup
await fastify.register(responseValidator, {
 ajv: {
 coerceTypes: true
 }
})

You can also pass in an instance of ajv

// Default configuration:
// coerceTypes: false
// useDefaults: true
// removeAdditional: true
// allErrors: true
import responseValidator from '@fastify/response-validation'
import Ajv from 'ajv'
// ... App setup
const ajv = new Ajv()
await fastify.register(responseValidator, { ajv })

By default, the response validation is enabled on every route that has a response schema defined. If needed you can disable it all together with responseValidation: false:

import responseValidator from '@fastify/response-validation'
// ... App setup
await fastify.register(responseValidator, {
 responseValidation: false
})

Alternatively, you can disable a specific route with the same option:

fastify.route({
 method: 'GET',
 path: '/',
 responseValidation: false,
 schema: {
 response: {
 '2xx': {
 type: 'object',
 properties: {
 answer: { type: 'number' }
 }
 }
 }
 },
 handler: async (req, reply) => {
 return { answer: '42' }
 }
})

Plugins

You can also extend the functionalities of the ajv instance embedded in this validator by adding new ajv plugins.

fastify.register(require('fastify-response-validation'), {
 ajv: {
 plugins: [
 require('ajv-formats'),
 [require('ajv-errors'), { singleError: false }]
 // Usage: [plugin, pluginOptions] - Plugin with options
 // Usage: plugin - Plugin without options
 ]
 }
})

Errors

The errors emitted by this plugin are:

FST_RESPONSE_VALIDATION_FAILED_VALIDATION: This error is emitted when a response does not conform to the provided schema.
FST_RESPONSE_VALIDATION_SCHEMA_NOT_DEFINED: This error is emitted when there is no JSON schema available to validate the response.