Awesome
<p align='right'>A <a href="http://www.swisspush.org">swisspush</a> project <a href="http://www.swisspush.org" border=0><img align="top" src='https://1.gravatar.com/avatar/cf7292487846085732baf808def5685a?s=32'></a></p>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 src="http://somewhere/path-to-docson/public/js/widget.js" data-schema="/path-to/schema.json"> </script>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
, 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:
<script src='/path-to-docson/docson-swagger.js' type='text/javascript'></script>
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
<script src='/lib/swagger.js' type='text/javascript'></script>
with
<script src='https://raw2.github.com/lbovet/swagger-js/models-exposed/lib/swagger.js' type='text/javascript'></script>
For a better layout of parameter models, you may want to change the width of some elements:
<style>
.swagger-ui-wrap {
max-width: 1200px;
}
.swagger-ui-wrap .body-textarea {
width: 200px;
}
</style>
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.