Automat API Documentation - human-readable text descriptions are missing

[karafecho]

The updated API Documentation is a big improvement and really nice. However, what is missing is simple two-sentence descriptions of each data source and endpoint in a human-readable format, with a link to an external source (e.g., CTD's main page) when available. This will be critical for subject matter experts who are not developers.

[karafecho]

I'll add that while a "JSON about dataset" feature is available for each dataset/endpoint, the JSON description will not be what most end users are interested in seeing.

[cbizon]

Discussed at the 3/13 UI meeting

[Woozl]

From #119

• OpenAPI supports CommonMark markdown in the description tags, which is rendered as rich text on the new docs site. All "human-readable" documentation can live alongside the the schema in the json doc. We can also host images for the documentation if necessary for diagrams, etc.
  • you can try this out on the Swagger editor as well
  • Markdown, if unfamiliar

[karafecho]

I am familiar with markdown and have worked with Swagger editors. The question is who will be providing the text. I am happy to do so, but I do not want to duplicate efforts.

[Woozl]

graph descriptions are returned by the /metadata endpoint, see #126