@brightcove/openapi-validator-hono

Hono OpenAPI Validator

Provides Hono middlewares for OpenApi validation

Installation

npm install @brightcove/openapi-validator-hono

Pre-parsing YAML files

If you pass in a path to a YAML file, the library will parse it on initialization into JSON. For particularly large YAML files, this can lead to slow startup times, so the library offers the ability to pre-parse YAML files.

npx @brightcove/openapi-validator-hono parse

Command List

  help      help
  parse     parses all YAML files in the specified folder into JSON

Options

  -i, --import    Folder path to read YAML files from (default: "api")
  -e, --export    Folder path to export JSON files to  (default: "api")

Initialization

The library needs to be initialized with the path to a valid YAML and/or JSON file.

import { Hono } from 'hono';
import path from 'path';
import { OpenApiValidator } from '@brightcove/openapi-validator-hono';

const app = new Hono();

app.use(OpenApiValidator.init([
    {
        name: 'api',
        yamlPath: path.resolve('./api/index.yaml')
    },
    options
]));

Note: If there is only a single API added, the api name can be omitted from all the middleware

Options

Validator Options

Field	Type	Description	Required
logger	Logger	The logger that will be used for debug messages. Uses console by default if not specified	false

API Options

Field	Type	Description	Required
name	string	Name used to retrieve the API	yes
yamlPath	string	Path to the OpenAPI YAML file	yes, to view docs, or jsonPath must be included
jsonPath	string	Path to the OpenAPI JSON file	yes, or yamlPath must be included
emptyRequestValid	boolean	Determines whether empty request bodies, for requests with required: true and no required properties, are considered valid. By default this is true.	no
errorCodes	object	Allows overriding of the default error code values	no
errorCodes.InputValidationException	string	Overrides the InputValidationException code. Is "400.00" by default.	no
errorCodes.OutputValidationException	string	Overrides the OutputValidationException code. Is "500.00" by default.	no

Validating Routes

The library provides the middleware validateRequest, validateResponse, and validate depending on whether you only want request or response validation, or both.

Note: If the middleware isn't added to the specific route, it will not function properly. This is because the routePath isn't resolved before the matching handler is determined

Any errors will be forwarded to the configured error handler as an InputValidationException or OutputValidationException

import { OpenApiValidator } from '@brightcove/openapi-validator-hono';

app.post(
    '/my/test/route',
    OpenApiValidator.validate('api'),  // alternatively `OpenApiValidator.validate()`
    async (c, next) => {
        ...
    }
);

app.onError((err, c) => {
    // err will be an `InputValidationException` or `OutputValidationException`
    if (err instance of HttpException) {
        return err.getResponse();
    }
});

Caveats

• anyOf and oneOf aren't properly validated, so it's suggested to avoid these and have the logic for validation elsewhere
• Nested schema refs will allow additional properties unless explicitely given additionalProperties: false

Information

Information on the API and the current route (if found) is added to the context when any of the validation middleware are attached.

If information is needed without any validation being performed, an info middleware is also available.

import { OpenApiValidator } from '@brightcove/openapi-validator-hono';

app.post(
    '/my/test/route',
    OpenApiValidator.info('api'),
    async (c, next) => {
        const openapi = c.get('openapi');
        const routeSchema = openapi.routeSchema;
        const apiSchema = openapi.schema;
        const operations = openapi.operations;
        ...
    }
);

Helper Functions

Some of the packages helper functions are exposed in the helpers export

import { helpers } from '@brightcove/openapi-validator-hono';

// Merges additional properties (ie. `allOf`) and `properties`
const merged = helpers.mergeSchema(jsonSchema);

// Checks whether an OpenApi schema json is valid, and returns any errors found if it isn't
const { valid, errors } = helpers.validateSchema(jsonSchema);

// Simple check for whether a JSON object is a valid OpenApi schema definition
const isValid = helpers.isValidSchema(json);

Errors

Error classes and helper functions are exposed with the errors export if a custom validation error needs to be thrown.

import { errors } from '@brightcove/openapi-validator-hono';

app.get('/some/route/1', async (c, next) => {
    ...something happens
    throw errors.InputValidationException('failed input validation');
});

app.get('/some/route/2', async (c, next) => {
    ...something happens
    throw errors.OutputValidationException('failed output validation');
});

JSON Schema Route

To view the JSON schema representation of the YAML file, you can use the following middleware

import { OpenApiValidator } from '@brightcove/openapi-validator-hono';

app.get('/schema', OpenApiValidator.schema('api'));

Documentation Route

To view a Swagger UI render of the OpenAPI spec, you can either specify the path to the YAML file (ie. if you're serving static files) or a full url

import { serveStatic } from '@hono/node-server/serve-static'; import { OpenApiValidator } from '@brightcove/openapi-validator-hono';

app.use('/static/*', serveStatic({ root: './api' }));

app.get('/docs', OpenApiValidator.docs('/static/'));