Package: json-schema-for-humans
JSON Schema for HumansQuickly generate a beautiful static HTML or Markdown page documenting a JSON schemaDocumentation (with visual examples)FeaturesSupport for JSON Schema Draft-07Since the result is static, it is easier to host and faster to loadHTML and Markdown output supportDifferent templates to choose from. More details:HTML version-Markdown versionAnchor links, allow to send a user to a specific section of the documentationSupport for references (even circular!)Installationpip install json-schema-for-humansUsageOptions for generation of the doc are documented using the library itself:HTML version-Markdown versionThey can be supplied in various ways:Using a JSON or YAML configuration file with the CLI option--config-fileUsing the CLI option--configUsing theConfigurationOptionobject from codeMore details are available in the appropriate sections below.From CLIgenerate-schema-doc [OPTIONS] SCHEMA_FILES_OR_DIR [RESULT_FILE_OR_DIR]SCHEMA_FILES_OR_DIRcan be:a path to a single schema file;a path to a directory, in this case all files with extensions json, yaml, or yml will be used;aglob pattern(starts from the current working directory); ora comma-separated list of the aboveAll schemas provided must be a valid JSON Schema (in JSON or YAML format)Examples:my_schema.jsonmy_foldermy_folder/my_schema.yaml,another_schema.json**/*.yaml.*The default value forRESULT_FILE_OR_DIRdepends on the context:the current working directory if more than one schema as been provided as inputschema_doc.htmlif rendering a single schema as HTMLschema_doc.mdif rendering a single schema as MarkdownIn a case where more than one schema is provided as input,RESULT_FILE_OR_DIRmust be a directory. The output documentation will have the same name as the input schema, but with a different extension (htmlormd).Choosing a templateTo choose a template on the CLI, use--config template_name=[TEMPLATE_NAME].
For example--config template_name=js(HTML) or--config template_name=md(Markdown).
The list of available templates isdocumented hereCLI options--configSupply generation config parameters. The parameters are documented in the JSON schemaconfig_schema.jsonat the root of the repo or see the generated doc:HTML version-Markdown version.Each parameter is in the format--config parameter_name=parameter_value. Example:--config expand_buttons=true. The parameter value must be valid JSON.For flags, you can also omit the value fortrueor prefix the parameter name withno_forfalse. Example:--config expand_buttonsor--config no_expand_buttons.--config-filePath to a JSON or YAML configuration file respecting the schemaconfig_schema.json.Example:--config-file jsfh-conf.yamlwherejsfh-conf.yamlis in the current directory and contains the following:description_is_markdown:falseexpand_buttons:truecopy_js:falseFrom codeThe following methods are available to import fromjson_schema_for_humans.generateMethod NameSchema inputOutputCSS and JS copied?generate_from_schemaschema_fileas str orpathlib.PathRendered doc as a strNogenerate_from_filenameschema_file_nameas str orpathlib.PathRendered doc written to the file at pathresult_file_nameYesgenerate_from_file_objectschema_fileas an open file object (read mode)Rendered doc written to the file atresult_file, which must be an open file object (in write mode)YesNotes:When using file objects, it is assumed that files are opened with encoding "utf-8"CSS and JS files are copied to the current working directory with names "schema_doc.css" and "schema_doc.min.js" respectively, if necessaryOther parameters of these methods are analogous to the CLI parameters documented above.The GenerationConfiguration objectTo reduce the number of parameters to pass from function to function in the code, there is aGenerationConfigurationobject that should be used for providing options.Example:fromjson_schema_for_humans.generateimportgenerate_from_filenamefromjson_schema_for_humans.generation_configurationimportGenerationConfigurationconfig=GenerationConfiguration(copy_css=False,expand_buttons=True)generate_from_filename("my_schema.json","schema_doc.html",config=config)# Your doc is now in a file named "schema_doc.html". Next to it, "schema_doc.min.js" was copied, but not "schema_doc.css"# Your doc will contain a "Expand all" and a "Collapse all" button at the topPre-load schemasgenerate_from_schemahas aloaded_schemasparameter that can be used to pre-load schemas. This must be a dict with the key being the real path of the schema file and the value being the result of loading the schema (withjson.loadoryaml.safe_load, for example).This should not be necessary in normal scenarios.What's supportedSee the excellentUnderstanding JSON Schemato understand what are those checksThe following are supported:TypesRegular expressionsString lengthString formatNumeric types multiples and rangeConstant and enumerated valuesRequired propertiesPattern propertiesDefault valuesArrayminItems,maxItems,uniqueItems,items,prefixItems,additionalItems, andcontainsCombining schema withoneOf,allOf,anyOf, andnotExamplesConditional subschemasThese arenotsupported at the moment (PRs welcome!):Property names and sizeProperty dependenciesMediaReferencesReferences are supported:To another part of the schema, e.g.{ $ref: "#/definitions/something" }To a local file,{"$ref": "references.json"},{"$ref": "references.json#/definitions/something"},{"$ref": "file:references.json"},{"$ref": "file:references.json#/definitions/something}To a URL,{"$ref": "http://example.com/schema.json"},{"$ref": "http://example.com/schema.json#/definitions/something"}Youcanhave adescriptionnext to a$ref, it will be displayed in priority to the description from the referenced element.If you have several attributes using the same definition, the definition will only be rendered once.
All other usages of the same definition will be replaced with an anchor link to the first render of the definition.
This can be turned off using--config no_link_to_reused_ref. SeeWith referencesin the examples.TemplatesTemplates control the style of the generated documentation.jsThis is the default template. It uses Bootstrap along with minimal Javascript to allow for the following:Properties are in expandable dynamic sections. You can include a button to expand or collapse all. (See doc:HTML version-Markdown version)Conditional subschemas (anyOf,oneOf,allOf) are in tabbed sectionsAnchor links will scroll to, expand, and animate the target sectionLong descriptions are collapsed by defaultWhen using this template, you need to include the Javascript file (schema_doc.min.js) that is automatically copied next to the output HTML file (schema_doc.htmlby default).js_offlineThis schema is identical to the js template, but all CSS and JavaScript resources are bundled so that the generated documentation can be used in an offline setting.flatNote: This template is a work in progressIt is sometimes not possible or desirable to include custom Javascript in documentation. This template addresses this issue by removing interactive elements in favor of simpler HTML.At the moment, this means the whole documentation is generated without any collapsible sections, which may make it hard to understand the schema structure. Contributions are welcomed to improve it!MD (Markdown)Note: This template is a work in progressThis template allows users to publish the generated documentation without hosting an HTTP server.On GitHub, this format is rendered directly when browsing code.A table of content is provided at the beginning of the file for easy navigation.You can display some important information as badge using an option.
See doc:HTML version-Markdown versionContributions are welcomed to improve it!ContributingSee CONTRIBUTING.md