Docson

Documentation for your JSON types.

Give Docson a JSON schema and it will generate a beautiful documentation.

Features

• JSON schema v4 keywords.
• Runs entirely in the browser.
• Render schema descriptions with markdown

Installation

• Place the Docson distribution on the web server serving the schemas (to avoid cross-origin issues).

Usage

• Open index.html and enter the schema path in the form field.
• Or give the schema path directly as hash parameter: index.html#/docson/examples/example.json

Note that you can refer to a sub-schema by adding a json-pointer path as 'dollar-parameter': index.html#/docson/examples/example.json$items

Typson

You can directly reference your JSON types defined as TypeScript interfaces. If the path ends with '.ts', Docson will use Typson to convert the Type Scripts to schema in order to generate the documentation.

For example, index.html#/typson/example/invoice/line.ts$InvoiceLine is the documentation of line.ts.

Typson must be located at the same level as the docson directory on your server. Keep its directory named typson.

Widget

To include a Docson schema documentations on any page (wiki, ...) without worrying about messing up with javascript libraries and cross-origin issues:

• Install Docson somewhere as described above.
• Place the following script tags in the including page, nothing else is needed:

<script src="http://somewhere/path-to-docson/widget.js" data-schema="/path-to-schema">
</script>

See the widget example on jsfiddle.

Integration

You can also integrate Docson in your application and use its javascript API:

docson.doc(element, schema, ref)

• element is the element which will host the documentation. Either a DOM element or jQuery element.
• schema is the URI or path to the schema or a string containing the schema source itself.
• ref is an optional json-pointer path to a sub-schema.

Examples:

• Simple integration example
• See it in action with its buddy typson.

Limitations

• Mixing unrelated keywords can lead to unexpected results.

Not implemented:

• Non-primitive values in enums and default values
• dependencies, additionalItems, patternProperties

Development

• All tests

Please pull-request your failing schemas in the tests/ folder and open an issue describing the expected result.