Automat API Issues - Githubissues

Here's a list of items that should be changed/fixed in the Automat API that I ran into while setting up the docs site.

[x] operationIds should be unique
- this is actually an OpenAPI schema error. You can see these errors by copypasting the Automat openapi.json into the Swagger editor
- these are used by the new docs site for the page URL, so they need to conform to the spec (right now I have a script to append a UUID so they are unique)
[x] servers.urls is an empty string, it should be automat.renci.org.
- This is used by the docs website for the interactive API query tool.
- I believe this is only working on the current swagger site because the docs are hosted at the same base URL as the API.
- https://swagger.io/docs/specification/api-host-and-base-path/

Here are some things to note:

The sidebar of the docs site is grouped by tags. For instance, all of the /biolink paths have the biolink tag, so they are all grouped together
- Some items have multiple tags, meaning they show up twice in the sidebar. For instance /biolink/1.3/meta_knowledge_graph has the biolink and trapi tags. This means when the user opens the "biolink" dropdown and clicks that page, the "trapi" dropdown also opens. This is not a great user experience, so I've opted to remove the trapi and translator sidebar dropdowns manually each time the site is generated. I'd like to propose removing these tags from the paths, if it's not too much trouble (i.e. each path has only one tag). Unfortunately, the plugin doesn't easily support generating the sidebar by a different method, but I will continue to look for other solutions.
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

RobokopU24 / Feedback