examples/biojson-doc/README.md

   1 <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>
   2 Docson
   3 ======
   4
   5 Documentation for your JSON types.
   6
   7 Give Docson a JSON schema and it will generate a [beautiful documentation](http://lbovet.github.io/docson/index.html#/docson/examples/example.json).
   8
   9 ## Features
  10 * [JSON schema](http://json-schema.org/) v4 keywords.
  11 * Runs entirely in the browser.
  12 * Render schema descriptions with markdown
  13
  14 ## Installation
  15
  16 * Place the Docson distribution on the web server serving the schemas (to avoid cross-origin issues).
  17
  18 ## Usage
  19
  20 * Open [index.html](http://lbovet.github.io/docson/index.html) and enter the schema path in the form field.
  21 * 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)
  22
  23 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)
  24
  25 ## Typson
  26
  27 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.
  28
  29 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).
  30
  31 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.
  32
  33 ## Widget
  34
  35 To include a Docson schema documentations on any page (wiki, ...) without worrying about messing up with javascript libraries and cross-origin issues:
  36
  37 * Install Docson somewhere as described above.
  38 * Place the following `script` tags in the including page, nothing else is needed:
  39
  40 ```
  41 <script src="http://somewhere/path-to-docson/widget.js" data-schema="/path-to-schema">
  42 </script>
  43 ```
  44
  45 See the [widget example](http://jsfiddle.net/3kXu2/3/) on jsfiddle.
  46
  47 ## Swagger
  48
  49 You can adapt [Swagger UI](https://github.com/wordnik/swagger-ui) to display Docson-generated model documentation instead of the builtin signatures.
  50
  51 See how it looks like in the [Swagger Docson example](http://lbovet.github.io/swagger-ui/dist/index.html)
  52
  53 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):
  54 ```
  55   <script src='/path-to-docson/docson-swagger.js' type='text/javascript'></script>
  56 ```
  57
  58 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
  59
  60 ```
  61    <script src='/lib/swagger.js' type='text/javascript'></script>
  62 ```
  63
  64 with
  65
  66 ```
  67   <script src='https://raw2.github.com/lbovet/swagger-js/models-exposed/lib/swagger.js' type='text/javascript'></script>
  68 ```
  69
  70 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):
  71
  72 ```
  73   <style>
  74       .swagger-ui-wrap {
  75           max-width: 1200px;
  76       }
  77       .swagger-ui-wrap .body-textarea {
  78           width: 200px;
  79       }
  80   </style>
  81 ```
  82
  83 ## Integration
  84
  85 You can also integrate Docson in your application and use its javascript API:
  86
  87 ```javascript
  88 docson.doc(element, schema, ref)
  89 ```
  90
  91 * `element` is the element which will host the documentation. Either a DOM element (id or object) or jQuery element.
  92 * `schema` is the URI or path to the schema or a string containing the schema source itself.
  93 * `ref` is an optional json-pointer path to a sub-schema.
  94
  95 Examples:
  96 * [Simple integration example](http://lbovet.github.io/docson/examples/example.html)
  97 * [See it in action](http://lbovet.github.io/typson-demo/) with its buddy [typson](https://github.com/lbovet/typson).
  98
  99 ## Limitations
 100
 101 * Mixing unrelated keywords can lead to unexpected results.
 102
 103 Not implemented:
 104 * Non-primitive values in enums and default values
 105 * dependencies, additionalItems, patternProperties
 106
 107 ## Development
 108
 109 * [All tests](http://lbovet.github.io/docson/tests/test.html)
 110
 111 Please pull-request your failing schemas in the `tests/` folder and open an issue describing the expected result.
 112
 113 [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/lbovet/docson/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
 114