Skip to content

john-doherty/jsdoc-to-json-schema

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

37 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

jsdoc-to-json-schema

Shippable branch npm

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

Installation

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

Example

Using this module within your node project

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 });

Using this module via the command line

# 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

Using this module as an expressjs response

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

Input (singleton)

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

/**  * @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: '' };

Output

{ "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" } } }

Input (instance)

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

/**  * @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(){ }

Output

{ "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

About

Generate JSON schemas from JavaScript code comments using jsDoc @Schema tag.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published