docson

by lbovet

lbovet /docson

Documentation for your JSON types

448 Stars 99 Forks Last release: Not found Apache License 2.0 169 Commits 6 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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

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.

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

typson
located at the same level as the
docson
directory.

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
, include the Swagger integration script after other script tags:
  

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
file in your Swagger UI disctribution or take it directly from github by replacing
   

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

Please pull-request your failing schemas in the

tests/
folder and open an issue describing the expected result.

Bitdeli Badge

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.