Convert JSON Schema to human-readable Markdown documentation
Project description
jsonschema2md
Convert JSON Schemas to simple, human-readable Markdown documentation.
For example:
{
"$id": "https://example.com/person.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Person",
"description": "JSON Schema for a person object.",
"type": "object",
"properties": {
"firstName": {
"type": "string",
"description": "The person's first name."
},
"lastName": {
"type": "string",
"description": "The person's last name."
}
}
}
will be converted to:
Person
JSON Schema for a person object.
Properties
firstName
(string): The person's first name.lastName
(string): The person's last name.
See the examples directory for more elaborate examples.
Installation
Install with pip
pip install jsonschema2md
Usage
From the CLI
jsonschema2md [OPTIONS] <input.json> <output.md>
From Python
import json
import jsonschema2md
parser = jsonschema2md.Parser(
examples_as_yaml=False,
show_examples="all",
)
with open("./examples/food.json", "r") as json_file:
md_lines = parser.parse_schema(json.load(json_file))
print(''.join(md_lines))
Options
examples_as_yaml
: Parse examples in YAML-format instead of JSON. (bool
, default:False
)show_examples
: Parse examples for only the main object, only properties, or all. (str
, defaultall
, options:object
,properties
,all
)show_deprecated
: Show deprecated properties. (bool
, default:True
)collapse_children
: Collapse object children into a<details>
element (bool
, default:False
)header_level
: Base header level for the generated markdown. (int
, default:0
)ignore_patterns
: List of regex patterns to ignore when parsing the schema. (list of str
, default:None
)
pre-commit hook
You can use the pre-commit hook with:
repos:
- repo: https://github.com/sbrunner/jsonschema2md
rev: <version> # Use the ref you want to point at
hooks:
- id: jsonschema2md
files: schema.json
args:
- --pre-commit
- schema.json
- schema.md
Contributing
Bugs, questions or suggestions? Feel free to post an issue in the issue tracker or to make a pull request! See Contributing.md for more info.
Install the pre-commit hooks:
pip install pre-commit
pre-commit install --allow-missing-config
Changelog
See Changelog.md.
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
jsonschema2md-1.5.2.tar.gz
(11.4 kB
view details)
Built Distribution
File details
Details for the file jsonschema2md-1.5.2.tar.gz
.
File metadata
- Download URL: jsonschema2md-1.5.2.tar.gz
- Upload date:
- Size: 11.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
338cc3909a25d1424b6823b13e17782d40f0faed97be42ba8abb22b96a1d82f9
|
|
MD5 |
a06c6792c3856110ab5503f0cccf0aaa
|
|
BLAKE2b-256 |
1c40fa685991204a0ae72e486720add480b8f21088e4a62c238c50fba506b9d6
|
File details
Details for the file jsonschema2md-1.5.2-py3-none-any.whl
.
File metadata
- Download URL: jsonschema2md-1.5.2-py3-none-any.whl
- Upload date:
- Size: 12.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
50492b944514ceac69d979d410b1a8a865c6a05a9bbc65a6a277ce10a61a9cab
|
|
MD5 |
eaa28dd54f878741d777187b5ec73929
|
|
BLAKE2b-256 |
74417a4b0ae6bff4ca1938f51943a0b77804acf459357f570f72d78567dc9570
|