Skip to main content

Generate static HTML documentation from JSON schemas

Project description

JSON Schema for Humans

Quickly generate a beautiful HTML static page documenting a JSON schema

Documentation

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

--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), and contains
  • Combining schema with oneOf, allOf, anyOf, and not

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 are supported (for example { $ref: "#/definitions/something" } will be replaced by the content of schema["definitions"]["something"])

References to schemas in other files are not supported for now.

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 from tests/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

json-schema-for-humans-0.3.0.tar.gz (21.6 kB view details)

Uploaded Source

Built Distribution

json_schema_for_humans-0.3.0-py3-none-any.whl (11.5 kB view details)

Uploaded Python 3

File details

Details for the file json-schema-for-humans-0.3.0.tar.gz.

File metadata

  • Download URL: json-schema-for-humans-0.3.0.tar.gz
  • Upload date:
  • Size: 21.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.42.0 CPython/3.7.6

File hashes

Hashes for json-schema-for-humans-0.3.0.tar.gz
Algorithm Hash digest
SHA256 8797409178c0d33b4cbe8fc1c0bb1be64cc9f9f43d61ef12475a5b20510cd84d
MD5 d39cfe89d02512040d5222a1f16a90b3
BLAKE2b-256 98a4b44bfd696579ef83ae40f200bdeb58815d3b28a406fd4383d144bce52a10

See more details on using hashes here.

File details

Details for the file json_schema_for_humans-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: json_schema_for_humans-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 11.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.42.0 CPython/3.7.6

File hashes

Hashes for json_schema_for_humans-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2d90f814ac5a36191cee9f7f3813fce6285b45e7d1feaf5414e27d38f9da5b99
MD5 15231abf8406044e4e7a00ad3c4199a0
BLAKE2b-256 fb044008af3d9c5b5f553a07aeecaadb705635c8a9403117ca503ae0651d7f01

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page