JSON schema to markdown generator (jsonschema2mk)

This project allows to generate documentation from JSON Schema spezifications.

Examples:

Supported JSON schema features

Basic attributes:
- title, description, default, examples
- enum, const
- deprecated
- $ref locally
number, integer
- minimum, maximum, exclusiveMinimum, exclusiveMaximum
- multipleOf
string
- minLength, maxLength
- format
- pattern
- contentMediaType
- contentEncoding
boolean
null
object
- properties
- additionalProperties (as boolean and as object)
- patternProperties
- required
- minProperties, maxProperties
- propertyNames.pattern
array
- items (schema)
- items (array of schemas)
- minItems, maxItems
- uniqueItems
- contains
- minContains, maxContains
allOf, oneOf, anyOf, not (not for object properties)
multiple types (type: ["string", "null"])

Missing JSON schema features

if, then, else
object: dependencies (Properties and Schema)

Install & Usage

npm install jsonschema2mk

Generate DOC.md:

npx jsonschema2mk --schema schema.json >DOC.md

Overwrite some partials with own partials:

npx jsonschema2mk --schema schema.json --partials dir/ >DOC.md

Add to your project

Add to package.json:

{
	"scripts": {
		"doc": "jsonschema2mk --schema schema.json >DOC.md"
	}
}

and run npm run doc.

Command line options

Usage:

npx jsonschema2mk [<options>] >DOC.md

Option	Description
`--schema schema.json`	Specify a JSON Schema file to convert. Default: `schema.json`
`--partials dir`	Overwrite partials from dir. You can overwrite every partial (see directory partials/) or define own ones. This option can be used multiple times.
`--extension ext`	Load feature extension. See section. This option can be used multiple times.
`--plugin p`	Load plugin. See section. This option can be used multiple times.
`--level number`	Initial Markdown heading level. Defaul is Zero.

Internal Feature Extensions (Option extension)

You can load feature extensions if needed.

Implemented Extensions:

yaml-examples: Show examples in YAML format.

Example Call:

npx jsonschema2mk --schema schema.json --extension yaml-examples --extension abc >DOC.md

Load External Plugins (Option plugin)

If partial overwriting is not enogh (see above), you can load plugins.

In the plugin, you can load your own partials. It has the same API as extensions.

The Arguments Vector is available via data.argv.

Example:

module.exports = function(data, jsonschema2mk) {
	jsonschema2mk.load_partial_dir(__dirname + "/partials");
};

Call it via:

npx jsonschema2mk --schema schema.json --plugin my-plugin.js >DOC.md

Usage as Libray

You can integration this code as Library. See cli.js for an example.

Examples

The README.md files of all applications of the osiota project are generated with the help of this program. See the adaption script in the osiota-dev repository as well.