jaketf/jsonschema2md

Convert JSON Schemas to simple, human-readable Markdown documentation.

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, default all, options: object, properties, all)

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.

Changelog

See Changelog.md.

jsonschema2md's Issues

Dependencies not making it to markdown

Hello awesome library maintainer 👋 .

I'm started to get into more complicated json schema with dependencies and was hoping this tool could help me document them! With the below yaml, only the enable_cluster is making it to the docs, not shard_count.

params:
  properties:
    enable_cluster:
      type: boolean
      title: Redis clustering
      default: false
  required:
    - enable_cluster
  dependencies:
    enable_cluster:
      oneOf:
        - properties:
            enable_cluster:
              enum:
                - true
            shard_count:
              type: integer
              title: Redis cluster shard count
              default: 1
              enum:
                - 1
                - 2
                - 3
                - 4
                - 5
        - properties:
             enable_cluster:
               enum:
                 - false