At our meeting on 3/13, @cbizon found an interesting scenario on the new docs site (swagger replacement). The new site, unlike swagger, only generates the information from the openapi.json file at build time. We were trying to get the metadata from ctd using the new docs site, but in the time I had last generated them, the metadata endpoint had changed from /ctd/about to /ctd/metadata, so the API returned a 404.
The swagger method of fetching and displaying the most recent version of the schema file is certainly convenient and prevents issues like this. On the other hand, it's probably good practice to get into versioning the changes to the API using the OpenAPI standards. In this case, the API hasn't been "released" so it's fine, but we should have the a version number in the base URL so researchers' projects aren't broken by a change in the API:
Unfortunately, because the site's generated at build time, small content changes in the documentation (clarifying something, adding a diagram), also will not show up until the site is rebuilt. However, content changes could be indicated by a bump to the patch number in the schema document (x.x.1 -> x.x.2). I'll take a look at how patch changes could be automated using a github action.
cbizon
commented
4 months ago
At our meeting on 3/13, @cbizon found an interesting scenario on the new docs site (swagger replacement). The new site, unlike swagger, only generates the information from the
openapi.jsonfile at build time. We were trying to get the metadata fromctdusing the new docs site, but in the time I had last generated them, the metadata endpoint had changed from/ctd/aboutto/ctd/metadata, so the API returned a 404.The swagger method of fetching and displaying the most recent version of the schema file is certainly convenient and prevents issues like this. On the other hand, it's probably good practice to get into versioning the changes to the API using the OpenAPI standards. In this case, the API hasn't been "released" so it's fine, but we should have the a version number in the base URL so researchers' projects aren't broken by a change in the API:
automat.renci.org/v1/...automat.renci.org/v2/...The docs plugin we're using has a way to show versions of the API, you can see how that looks here: https://docusaurus-openapi.tryingpan.dev/category/petstore-versioned-api
Unfortunately, because the site's generated at build time, small content changes in the documentation (clarifying something, adding a diagram), also will not show up until the site is rebuilt. However, content changes could be indicated by a bump to the patch number in the schema document (x.x.1 -> x.x.2). I'll take a look at how patch changes could be automated using a github action.
Let me know how we feel about this.