A swisspush project

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).
• If you want to use Docson without a web server, you may be interested in the Offline Usage Tutorial.

Usage

Via cli tool

$ docson -d ./schemas/
server ready and running at localhost:3000

and then...
firefox http://localhost:3000/schemas/ship.json

As a webpage 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:

Add to a webpage

• 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

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

You need to install Typson by yourself on your server. It must be in a directory named

typson

docson

Swagger

You can adapt Swagger UI to display Docson-generated model documentation instead of the builtin signatures.

See how it looks like in the Swagger Docson example

In Swagger UI's

index.html

Also, you will need a patched version of Swagger Client so that the raw json-schema model is visible from Docson. Either replace the

swagger.js

with

For a better layout of parameter models, you may want to change the width of some elements:

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 (id or object) 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/