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.
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.
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.
operationId
s should be uniqueservers.urls
is an empty string, it should beautomat.renci.org
.Here are some things to note:
/biolink
paths have thebiolink
tag, so they are all grouped together/biolink/1.3/meta_knowledge_graph
has thebiolink
andtrapi
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 thetrapi
andtranslator
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.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.