EES-5664 Update public API docs to handle multiple API versions #5397
Conversation
ntsim
force-pushed
the
ees-5664
branch
6 times, most recently
from
8e12de0 to
195ab3e
Compare
ntsim
force-pushed
the
ees-5664
branch
3 times, most recently
from
2624f27 to
c801f14
Compare
|
|
||
| # OpenAPI documents | ||
|
|
||
| The explore education statistics (EES) API is fully compliant with the [OpenAPI 3.0 specification](https://swagger.io/specification/v3/). |
There was a problem hiding this comment.
Would suggest capitalising the first "e"?
There was a problem hiding this comment.
This would make intuitive sense, but the service name casing was decided by Cam.
I did argue the point that it's not particularly nice and potentially could be unclear to users, but he was pretty insistent.
Consequently, the convention is:
- Start of sentence - use 'Explore'
- Mid-sentence - use 'explore'
I think at some point he'll want us to go through the rest of the service and change it across the board as well.
|
|
||
| # <%= title %> | ||
|
|
||
| This section lists all the endpoints available on the explore education statistics (EES) <%= version %> API. |
There was a problem hiding this comment.
Capitalise the first "e" again?
There was a problem hiding this comment.
See comment: #5397 (comment)
|
|
||
| # <%= title %> | ||
|
|
||
| This section contains the reference documentation for the explore education statistics (EES) |
There was a problem hiding this comment.
See comment: #5397 (comment)
| if api_docs_path.nil? | ||
| return resources | ||
| end | ||
| if path != "source/openapi-#{version}.json" |
There was a problem hiding this comment.
Nice bit of sanity checking :)
| end | ||
| base_path = "/reference-#{version}" | ||
|
|
||
| resources << Middleman::Sitemap::ProxyResource.new( |
There was a problem hiding this comment.
I'm just going to trust that this works! Kudos on working all of this out!
This PR updates the public API docs to handle multiple API versions (in the future). Previously, the API reference docs were only generated from a single OpenAPI document, meaning we couldn't publish docs for multiple API versions.
We can now generate API reference docs from any
openapi-v*.jsondocuments that are placed in thesourcedirectory.Config and environment changes
.envsupport in API docs project. This is for local development to make it easier to change and persist environment variable changes (if required).api_urlconfig option (orTECH_DOCS_API_URLenv variable) for API docs. This allows us to build for different environments in the build pipeline. We now default tohttp://localhost:5050for local development.Other changes
/. This makes the default document agnostic of the environment.DataSetLatestVersionViewModel.GeographicLevelsproperty