jsdoc-to-json-schema
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 = ; // OPTION 1: generate a JSON schema for product.js and save it to disk; // OPTION 2: generate a JSON schema and return it as an object; // OPTION 3: generate a JSON schema, save it to disk and return it as an object;
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 = ;var app = ;var toJsonSchema = ; // create an express routeapp; // start the server listening on port 8080app;
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 */{ } /** * @schema.type array * @schema.minItems 3 * @schema.maxItems 6 * @schema.required true */Productprototype{ }
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