Improvements to OpenAPI spec [meta-issue]

[dafeder]

This is a stub that needs to be broken out into a few specific tickets. Some possible improvements to our spec:

1. Look at the output of https://pb33f.io/doctor/ report on our spec, identifiy examples that should be added to improve score and fix any actual errors
2. Clearer separation of public API spec from private. Maybe show just public by default, or have a page on the admin side for the private/authenticated endpoints.
3. Separate metastore and datastore public APIs into two separate sections. Build out datastore API docs with more robust narrative/explanations, and explanations for how to do groupings, orderings etc.
4. Consolidate the metastore endpoints a bit more, it's a little confusing still how there are endpoints for datasets and then another set for schema as a parameter

[paul-m]

If I feed the tool https://demo.getdkan.org/api/1

I get:

Specification cannot be used:

unable to parse OpenAPI specification: unable to parse the document, no index was created, check the syntax or version of the document.

[dafeder]

Hmmm I copied and pasted the JSON and it worked. @paul-m if it's all minified it won't parse, you need to pretty-print it before copying.

Not sure why we don't pretty-print the /api/1 endpoint on our end though.