Auto-generate documentation from schemas

[bogaert]

A common request: auto-generate documentation from the schemas, because JSON schemas are hard to read and people don't document them.

[chuwy]

That would lovely! Any concrete examples?

[bogaert]

I don't have examples, I'll see whether I can find some.

A first good step might be to present all schemas in a more readable format (a simple table), so people who're not technical can understand what the fields are. An extension might be to allow people to annotate the schema or particular fields (e.g. what is the field supposed to capture?).

[fblundun]

Maybe a way to generate an example from a JSON schema?

e.g.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  }
}

would generate

{
  "name": "abc"
}

It may be harder to get this working for more complex schemas... Also, a single example can't tell you everything about the schema. For example, it can't tell you which fields are optional.

[chuwy]

This is a very interesting idea worth do discover.

I don't think it's worth to generate an instance out of Schema because 1) most of Schemas are generated with Schema Guru, so we have real instances; 2) it is really complicated task, I have a code which generates JSON out of Schema, but most of them contains non-sense values.

Idea with tables is nice. We're flattening Schemas in schema-guru ddl, we can do something similar for documentation purposes. One little problem is that tables are flat, and we inevitable will lost some information trying to represent nested structure.

One other good option I see now is docson, not very shiny UI, but it can be improved. Also I see an arising idea of manual documentation. JSON Schema provides description property. We can provide users of Scala repo ability to annotate their properties (through docson?).

[alexanderdean]

docson is a great find!

[bogaert]

Docson looks good. Longer term, it might indeed make sense to use description.

[dashirov-fl]

This has been on ice for the past 4 years. Has the feature been abandoned? Is there any reason to expect any traction on the subject any time soon?

[szareiangm]

@dashirov-fl we used this tool and added our schemas to a md website generator: https://github.com/adobe/jsonschema2md