Documentation for your JSON types
A swisspush project
Documentation for your JSON types.
Give Docson a JSON schema and it will generate a beautiful documentation.
$ docson -d ./schemas/ server ready and running at localhost:3000and then...
To include a Docson schema documentations on any page (wiki, ...) without worrying about messing up with javascript libraries and cross-origin issues:
Place the following
scripttags in the including page, nothing else is needed:
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
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
typsonlocated at the same level as the
docsondirectory.
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.jsfile 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:
You can also integrate Docson in your application and use its javascript API:
docson.doc(element, schema, ref)
elementis the element which will host the documentation. Either a DOM element (id or object) or jQuery element.
schemais the URI or path to the schema or a string containing the schema source itself.
refis an optional json-pointer path to a sub-schema.
Examples: * Simple integration example * See it in action with its buddy typson.
Not implemented: * Non-primitive values in enums and default values * dependencies, additionalItems, patternProperties
Please pull-request your failing schemas in the
tests/folder and open an issue describing the expected result.