jsdoc-to-json-schema

   

Generate JSON schemas from JavaScript code comments using a new jsDoc @schema tag.

Installation

``js
npm install --save jsdoc-to-json-schema
`

Example

$3

`js
var toJsonSchema = require('jsdoc-to-json-schema');

// OPTION 1: generate a JSON schema for product.js and save it to disk
toJsonSchema('./example/product.js', './example/product.schema.json');

// OPTION 2: generate a JSON schema and return it as an object
toJsonSchema('./example/product.js').then(function(schema){
// do something with it
});

// OPTION 3: generate a JSON schema, save it to disk and return it as an object
toJsonSchema('./example/product.js', './example/product.schema.json').then(function(schema){
// do something with it
});
`

$3

`bash


install the module globally

$ npm install -g jsdoc-to-json-schema

execute from command line passing input and output paths

$ jsdoc-to-json-schema -i ./example/product.js -o ./example/product.schema.json
`

$3

`js
var express = require('express');
var app = express();
var toJsonSchema = require('../lib/jsdoc-to-json-schema.js');

// create an express route
app.get('/', function(req, res){

// pipe schema directly to the response stream
toJsonSchema('./examples/person.js', res);
});

// start the server listening on port 8080
app.listen(8080, function(){
console.log('Example app listening on port 8080');
});
`

For use with express consider the dedicated express middleware project express-json-schema

$3

JavaScript file containing jsDoc @schema tags used to define the JSON schema:

`js
/**
* @schema.name Person
* @schema.description This is an example Person object marked up with JSON schema tags to allow schema generation
*/
var Person = {

/**
* @schema.title Name
* @schema.description Please enter your full name
* @schema.type string
* @schema.maxLength 30
* @schema.minLength 1
* @schema.required true
*/
name: '',

/**
* @schema.title Job Title
* @schema.type string
*/
jobTitle: '',

/**
* @schema.title Telephone Number
* @schema.description Please enter telephone number including country code
* @schema.type string
* @schema.required true
*/
telephone: '',

/**
* @schema.type string
* @schema.required true
*/
dateOfBirth: ''
};
`

$3

`js
{
"name": "Person",
"description": "This is an example Person object marked up with JSON schema tags to allow schema generation",
"properties": {
"name": {
"title": "Name",
"description": "Please enter your full name",
"type": "string",
"maxLength": 30,
"minLength": 1,
"required": true
},
"jobTitle": {
"title": "Job Title",
"type": "string"
},
"telephone": {
"title": "Telephone Number",
"description": "Please enter telephone number including country code",
"type": "string",
"required": true
},
"dateOfBirth": {
"type": "string",
"required": true
},
"address": {
"type": "object"
}
}
}
`

$3

JavaScript file containing jsDoc @schema tags used to define the JSON schema:

`js
/**
* @schema.name Product
* @schema.description An example product marked up with json schema comments
*/
function Product(){

}

/**
* @schema.type array
* @schema.minItems 3
* @schema.maxItems 6
* @schema.required true
*/
Product.prototype.types = function(){

}
`

$3

`js
{
"name": "Product",
"description": "An example product marked up with json schema comments",
"properties": {
"types": {
"type": "array",
"minItems": 3,
"maxItems": 6,
"required": true
}
}
}
`

Supported JSON Schema tags

The following JSON Schema v3 tags are supported, however undocumented @schema tags will also be generated in order to aid extensibility.

Note: @schema tags without an associated value will be ignored.

| Tag | Type
| -------------------------- | ---------
| @schema.name | string
| @schema.description | string
| @schema.extends | string
| @schema.id | string
| @schema.type | string
| @schema.pattern | string
| @schema.title | string
| @schema.format | string
| @schema.disallow | string
| @schema.enum | array
| @schema.minimum | integer
| @schema.maximum | integer
| @schema.minItems | integer
| @schema.maxItems | integer
| @schema.minLength | integer
| @schema.maxLength | integer
| @schema.exclusiveMinimum | integer
| @schema.exclusiveMaximum | integer
| @schema.divisibleBy | integer
| @schema.required | boolean
| @schema.uniqueItems | boolean
| @schema.default | any

Running tests

Install dev dependencies and run tests:

`
$ npm install -d && npm test
``

License

Licensed under ISC License © John Doherty