joi-to-swagger
Conversion library for transforming Joi schema objects into Swagger schema definitions.
// input
joi.object().keys({
id: joi.number().integer().positive().required(),
name: joi.string(),
email: joi.string().email().required(),
created: joi.date().allow(null),
active: joi.boolean().default(true),
})
// output
{
"type": "object",
"required": ["id", "email"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"created": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"active": {
"type": "boolean"
}
}
}
Usage
var j2s = require('joi-to-swagger');
var {swagger, definitions} = j2s(mySchema, existingDefinitions);
J2S takes two arguments, the first being the Joi object you wish to convert. The second optional argument is a collection of existing definitions to reference against for the meta className
identifiers (see below).
J2S returns a result object containing swagger
and definitions
properties. swagger
contains your new schema, definitions
contains any definitions that were generated while parsing your schema.
Supported Conventions:
-
joi.object()
.unknown(false)
->additionalProperties: false
.required()
on object members produces a"required": []
array
-
joi.array().items()
defines the structure using the first schema provided on.items()
(see below for how to override).min(4)
->"minItems": 4
.max(10)
->"maxItems": 10
.unique(truthy)
->"uniqueItems": true
-
joi.number()
produces"type": "number"
with a format of"float"
.precision()
->"format": "double"
.integer()
->"type": "integer"
.strict().only(1, 2, '3')
->"enum": [1, 2]
(note that non-numbers are omitted due to swagger type constraints).allow(null)
->"type": ["number", "null"]
.min(5)
->"minimum": 5
.max(10)
->"maximum": 10
.positive()
->"minimum": 1
.negative()
->"maximum": -1
-
joi.string()
produces"type": "string"
with no formatting.strict().only('A', 'B', 1)
->"enum": ["A", "B"]
(note that non-strings are omitted due to swagger type constraints).alphanum()
->"pattern": "/^[a-zA-Z0-9]*$/"
.alphanum().lowercase()
.alphanum().uppercase()
.token()
->"pattern": "/^[a-zA-Z0-9_]*$/"
.token().lowercase()
.token().uppercase()
.email()
->"format": "email"
.isoDate()
->"format": "date-time"
.regex(/foo/)
->"pattern": "/foo/"
.allow(null)
->"type": ["string", "null"]
.min(5)
->"minLength": 5
.max(10)
->"maxLength": 10
-
joi.binary()
produces"type": "string"
with a format of"binary"
..encoding('base64')
->"format": "byte"
.min(5)
->"minLength": 5
.max(10)
->"maxLength": 10
.allow(null)
->"type": ["string", "null"]
-
joi.date()
produces"type": "string"
with a format of"date-time"
..allow(null)
->"type": ["string", "null"]
-
joi.alternatives()
defines the structure using the first schema provided on.items()
(see below for how to override) -
any.default()
sets the"default"
detail.
Meta Overrides
The following may be provided on a joi .meta()
object to explicitly override default joi-to-schema behavior.
className: By default J2S will be full verbose in its definitions. If an object has a className
string, J2S will look for an existing definition with that name, and if a definition does not exist then it will create one. Either way, it will produce a $ref
element for that schema definition. If a new definition is created it will be returned with the swagger schema.
swaggerIndex: Swagger's deterministic design disallows for supporting multiple type definitions. Because of this, only a single schema from .alternatives()
and .array().items()
may be converted to swagger. By default J2S will use the first definition. Defining a different zero based index for this meta tag will override that behavior.
swagger: To explicitly define your own swagger definition for a joi schema object, place that swagger object in the swagger
meta tag. It will be mixed in to the schema that J2S produces.
swaggerOverride: If this meta tag is truthy, the swagger
definition will replace the result for that schema instead of mixing in to it.