JSON schema to markdown generator
npm install jsonschema2mkThis project allows to generate documentation from JSON Schema spezifications.
Examples:
* Configuration osiota ArtNet app (see project)
* Configuration osiota Modbus app (see project)
* Basic attributes:
* title, description, default, examples
* enum, const
* deprecated
* $ref is same file, $id, $anchor
* 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)
* if, then, else
* multiple types (type: ["string", "null"])
* object: dependencies (Properties and Schema)
* $ref remotely or in other files
``sh`
npm install jsonschema2mk
Generate DOC.md:
`sh`
npx jsonschema2mk --schema schema.json >DOC.md
Overwrite some partials with own partials:
`sh`
npx jsonschema2mk --schema schema.json --partials dir/ >DOC.md
Add to package.json:
`json`
{
"scripts": {
"doc": "jsonschema2mk --schema schema.json >DOC.md"
}
}
and run npm run doc.
Usage:
`sh`
npx jsonschema2mk [
| 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. Default is Zero. |
You can load feature extensions if needed.
Implemented Extensions:
table-format-2: Show tables with the columns name, type, title, description and required. Default is to display a combined name and title* column. See example output.
* yaml-examples: Show examples in YAML format.front-matter
* : Add a front matter block.--fm.para1 value1 --fm.para2 value2
You can define the front-matter with
Example Calls:
`sh`table-format 2
npx jsonschema2mk --schema schema.json \
--extension table-format-2 >DOC.mdyaml-examples
npx jsonschema2mk --schema schema.json \
--extension yaml-examples >DOC2.mdyaml-examples and front matter
npx jsonschema2mk --schema schema.json \
--extension yaml-examples \
--extension front-matter --fm.parent Reference --fm.nav_order 1 >DOC3.md
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:
`js`
module.exports = function(data, jsonschema2mk) {
jsonschema2mk.load_partial_dir(__dirname + "/partials");
};
Call it via:
`sh`
npx jsonschema2mk --schema schema.json --plugin my-plugin.js >DOC.md
You can integration this code as Library. See cli.js for an example.
`js
const jsonschema2mk = require("jsonschema2mk");
const schema = {
"type": "number"
};
const jsm = new jsonschema2mk({
level: 0
});
const output = jsm.convert(schema);
``
Options see CLI options
| Option | Type | Description |
|---|---|---|
| partials | string | Overwrite partials. Define dir, where to load partioals from. You can overwrite every partial (see directory partials/) or define own ones. This option can be used multiple times. |
| extension | string | Load feature extension. See section. This option can be used multiple times. |
| plugin | string | Load plugin. See section. This option can be used multiple times. |
| level | number | Initial Markdown heading level. Default is Zero. |
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.
Examples:
* osiota-app-modbus
* osiota-app-onewire
This software is released under the MIT license.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.