Closed karafecho closed 1 year ago
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.
Discussed at the 3/13 UI meeting
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
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.
graph descriptions are returned by the /metadata
endpoint, see #126
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.