Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lbovet/docson
Documentation for your JSON types
https://github.com/lbovet/docson
Last synced: 5 days ago
JSON representation
Documentation for your JSON types
- Host: GitHub
- URL: https://github.com/lbovet/docson
- Owner: lbovet
- License: apache-2.0
- Created: 2013-12-03T19:23:37.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2023-11-05T00:43:36.000Z (about 1 year ago)
- Last Synced: 2024-04-16T17:46:38.747Z (8 months ago)
- Language: JavaScript
- Size: 1.4 MB
- Stars: 490
- Watchers: 15
- Forks: 101
- Open Issues: 45
-
Metadata Files:
- Readme: README.md
- Changelog: Changes.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - lbovet/docson - Documentation for your JSON types (others)
README
A swisspush project 
Docson
======
Documentation for your JSON types.
Give Docson a JSON schema and it will generate a [beautiful documentation](http://lbovet.github.io/docson/index.html#/docson/examples/example.json).
## Features
* [JSON schema](http://json-schema.org/) 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](https://gist.github.com/riegl-aw/6b258499887fc3e302f0b5dbcfa7b3d9).
## 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](http://lbovet.github.io/docson/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](http://lbovet.github.io/docson/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](http://lbovet.github.io/docson/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](https://github.com/lbovet/typson) to convert the Type Scripts to schema in order to generate the documentation.
For example, [index.html#/typson/example/invoice/line.ts$InvoiceLine](http://lbovet.github.io/docson/index.html#/typson/example/invoice/line.ts$InvoiceLine) is the documentation of [line.ts](https://github.com/lbovet/typson/blob/master/example/invoice/line.ts).
You need to install [Typson](https://github.com/lbovet/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](https://github.com/wordnik/swagger-ui) to display Docson-generated model documentation instead of the builtin signatures.
See how it looks like in the [Swagger Docson example](http://lbovet.github.io/swagger-ui/dist/index.html)
In Swagger UI's `index.html`, include the [Swagger integration script after other script tags](https://github.com/lbovet/swagger-ui/blob/3f37722b03db6c48cc2a8460df26dda5f4d6f8e4/src/main/html/index.html#L19):
```html
```
Also, you will need a patched version of [Swagger Client](https://github.com/lbovet/swagger-js/blob/models-exposed/lib/swagger.js) 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
```html
```
with
```html
```
For a better layout of parameter models, you may [want to change the width of some elements](https://github.com/lbovet/swagger-ui/blob/3f37722b03db6c48cc2a8460df26dda5f4d6f8e4/src/main/html/index.html#L20-L27):
```html
.swagger-ui-wrap {
max-width: 1200px;
}
.swagger-ui-wrap .body-textarea {
width: 200px;
}
```
## Integration
You can also integrate Docson in your application and use its javascript API:
```javascript
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](http://lbovet.github.io/docson/examples/example.html)
* [See it in action](http://lbovet.github.io/typson-demo/) with its buddy [typson](https://github.com/lbovet/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](http://lbovet.github.io/docson/tests/test.html)
Please pull-request your failing schemas in the `tests/` folder and open an issue describing the expected result.
[](https://bitdeli.com/free "Bitdeli Badge")