Generate static HTML documentation from JSON schemas
Project description
JSON Schema for Humans
Quickly generate a beautiful HTML static page documenting a JSON schema
Installation
pip install json-schema-for-humans
Usage
generate-schema-doc [OPTIONS] SCHEMA_FILE [RESULT_FILE]
SCHEMA_FILE
must be a valid JSON Schema
A CSS file will be copied in the same directory as RESULT_FILE
The default value for RESULT_FILE
is schema_doc.html
Options
--expand-buttons
Off by default
Add an Expand all
and a Collapse all
button at the top of the generated documentation
--minify/--no-minify
On by default
Minify the output HTML document
--deprecated-from-description
Off by default
Mark a property as deprecated (with a big red badge) if the description contains the string [Deprecated
--default-from-description
Off by default
Extract the default value of a property from the description like this: [Default `the_default_value`]
The default value from the "default" attribute will be used in priority
What's supported
See the excellent Understanding JSON Schema to understand what are those checks
The following are supported:
- Types
- Regular expressions
- Numeric types multiples and range
- Constant and enumerated values
- Required properties
- Default values
- Array
minItems
,maxItems
,uniqueItems
,items
(schema that must apply to all of the array items), andcontains
- Combining schema with
oneOf
,allOf
,anyOf
, andnot
These are not supported at the moment (PRs welcome!):
- String length and format
- Property names, size, and pattern
- Array items at specific index (for example, first item must be a string and second must be an integer)
- Property dependencies
- Examples
- Media
- Conditional subschemas
References from inside a schema and to schemas in other files are supported (for example { $ref: "#/definitions/something" }
will be replaced by the
content of schema["definitions"]["something"]
).
Development
Testing
Just run tox
tox
Generating doc
The documentation is generated using jekyll and hosted on GitHub Pages
- Change your current working directory to
docs
- Run
python generate_examples.py
. This will get all examples fromtests/cases
, render the resulting HTML and include it in the appropriate folders in the jekyll site. - If you have added an example, add the file name (without
.json
), the display name and description in_data/examples.yaml
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 json-schema-for-humans-0.5.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7c224f1f4b551a9a1373631898c156aa8462da7bf019aec324b91acdc14b6cfb |
|
MD5 | 8f9553cd937de7560df781b9f0c4c135 |
|
BLAKE2b-256 | 8444378ecbcf5b81e4a77c4e0749886a870476483dd86c697c5fc6c3a0b302ab |
Hashes for json_schema_for_humans-0.5.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a34f1bb332915f4e61a5c9bbf0ffb7aa08581c7307330d536e0e8845934baa2b |
|
MD5 | 2afad5b3909cb878d4fdb315729a1ac1 |
|
BLAKE2b-256 | 0c6dd12089517621548000a42636ae4ecee0414b1ed99932d329be77e43f1fb2 |