Export a JSON Schema document to Markdown documentation.
Project description
jsonschema-markdown
Generate markdown documentation from JSON Schema files. The main goal is to generate documentation that is easy to read and understand.
Can be used as a command line tool or as a library.
Installation
pipx install jsonschema-markdown
Usage
To use jsonschema-markdown
as a CLI, just pass the filename as an argument and redirect
the output to a file.
$ jsonschema-markdown --help
Usage: jsonschema-markdown [OPTIONS] FILENAME
Load FILENAME and output a markdown version.
Use '-' as FILENAME to read from stdin.
Options:
-t, --title TEXT Do not use the title from the schema, use
this title instead.
--footer / --no-footer Add a footer with a link to the project.
[default: footer]
--empty-columns / --no-empty-columns
Remove empty columns from the output, useful
when deprecated or examples are not used.
[default: empty-columns]
--resolve / --no-resolve [Experimental] Resolve $ref pointers.
[default: no-resolve]
--debug / --no-debug Enable debug output. [default: no-debug]
--version Show the version and exit.
--help Show this message and exit.
# Example
$ jsonschema-markdown schema.json > schema.md
Usage with Docker
The jsonschema-markdown
command is also available as a Docker image. To use it, you can mount the schema file as a volume.
cat my-schema.json | docker run --rm -i elisiariocouto/jsonschema-markdown - > schema.md
⚠️ Warning: Do not pass the -t
flag.
The Docker image is available at:
Usage as a library
To use it as a library, load your JSON schema file as Python dict
and pass it to generate.
The function will return a string with the markdown.
import jsonschema_markdown
with open('schema.json') as f:
schema = json.load(f)
markdown = jsonschema_markdown.generate(schema)
Features
Partially inspired by json-schema-for-humans, this project does not currently support all features of JSON Schema, but it should support:
- Required fields
- String patterns
- Enumerations
- Default values
- Descriptions and titles
- Nested objects
- Basic OneOf, AnyOf, AllOf functionality
- Arrays
- Integers with minimum, maximum values and exclusives
- Boolean values
- Deprecation notices (searches for case-insensitive
deprecated
in the field description)
Caveats
- This project is still in early development, and the output may change in the future.
- Custom definitions are expected to be in the same file as the schema that uses them,
in the
definitions
or$defs
parameter at the root of the document.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jsonschema_markdown-0.3.9.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e0d98d9146486a1ff1f03a424e9ab2aa0cb66b00b236bb6b2ba390340ea7a75b |
|
MD5 | ac60d65ae4ec4aa2b6a5615c0b8c54cb |
|
BLAKE2b-256 | e986888cafdd0847ef71e3c8e3ee72ab6ce4ecca693be05b05649bdc08bf4850 |
Hashes for jsonschema_markdown-0.3.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3bfd18eefe781a1c0ba0687312b88ac5dc7625b5db678fbb510344e30fe499c8 |
|
MD5 | 4821061d03b5799b5309488c3a4be76a |
|
BLAKE2b-256 | 1aa8b397b5567b29d822f7aba2b49b6db3b8ad87686bab315838c26f08baf335 |