joi-to-swagger

library6.2.0jsnpmunverified

Converts Joi validation schemas into OpenAPI 3.0 schema definitions. Stable version 6.2.0, maintained on npm, with TypeScript definitions included. Key differentiator: directly maps Joi constraints (min, max, pattern, enum, nullable, etc.) to OpenAPI properties and supports `ref` components via a second argument. Requires Joi >=17.1.1 as a peer dependency. Alternative to manual OpenAPI schema authoring, useful for API documentation generators and validators that reuse existing Joi definitions.

devops

npm install joi-to-swagger

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JOI-TO-SWAGGER

joi-to-swagger

devopsjavascriptv6.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import j2s from 'joi-to-swagger';

✗ const j2s = require('joi-to-swagger').default;

Package has a CommonJS default export; ESM import works directly.

default (CommonJS)

✓ const j2s = require('joi-to-swagger');

✗ const { joiToSwagger } = require('joi-to-swagger');

No named export; only default export is available.

j2s result destructuring

✓ const { swagger, components } = j2s(schema, existingComponents);

✗ const result = j2s(schema); const swagger = result.schema;

Return object has properties 'swagger' and 'components', not 'schema'.

Converts a typical Joi user object schema into OpenAPI 3.0 schema definition, showing required fields, string format, nullable, and default.

const Joi = require('joi'); const j2s = require('joi-to-swagger'); const userSchema = Joi.object({ id: Joi.number().integer().positive().required(), name: Joi.string(), email: Joi.string().email().required(), created: Joi.date().allow(null), active: Joi.boolean().default(true), }); const { swagger } = j2s(userSchema); console.log(JSON.stringify(swagger, null, 2));

Debug

Known issues

gotchaSecond argument to j2s() is an object of existing OAS components for $ref resolution, but if not provided, components are created automatically.

fix

Pass in a components object if you need to reference existing definitions; otherwise omit.

affects: >=0.0.1

gotchaOnly Joi objects with a meta('className') property will generate named components; otherwise inline schemas are created.

fix

Add .meta({ className: 'MyModel' }) to Joi object schemas you want as reusable components.

affects: >=0.0.1

breakingVersion 6.0.0 dropped support for Node <10 and Joi <17.1.1.

fix

Upgrade Node.js to >=10 and Joi to >=17.1.1.

affects: >=6.0.0

deprecatedThe 'swagger' property in the returned object is actually OpenAPI 3.0, not Swagger 2.0; property name is legacy.

fix

Use the returned schema directly; consider renaming variable to 'openApi' for clarity.

affects: >=0.0.1

gotchajoi.alternatives().try() may not fully convert complex oneOf/anyOf structures; look out for incomplete conversions.

fix

Manually verify converted schemas for alternatives; file an issue on GitHub if broken.

affects: >=0.0.1

Errors

Common errors & fixes

Cannot find module 'joi-to-swagger'

Package not installed or not in node_modules.

fix

Run npm install joi-to-swagger joi

TypeError: j2s is not a function

Wrong import style; default imported as an object.

fix

Use const j2s = require('joi-to-swagger'); or import j2s from 'joi-to-swagger';

joi-to-swagger: could not parse schema - unrecognized Joi type

Using a Joi type not supported (e.g., joi.link(), joi.forbidden()).

fix

Check supported types in README; omit unsupported types or convert manually.

joi-to-swagger: schema must be a Joi object

Passed a non-Joi object or a plain object.

fix

Pass a valid Joi schema (e.g., Joi.object({...})).

Upgrade

Version history

6.2.0latest on npm

Audit

Dependencies

joirequiredpeer dependency — required at runtime to parse Joi schema objects; version must be >=17.1.1

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Twipped/joi-to-swagger ↗

packagejoi-to-swagger ↗

homepagehttps://github.com/Twipped/joi-to-swagger#readme ↗