ilabs-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.