==== Overview ====
The specs.v0 module is used to provide OpenAPI specs, which are useful to callers on their own, and which also are used by the REST Sandbox. This module has been in use in production for [[ https://gerrit.wikimedia.org/r/c/operations/mediawiki-config/+/1076058 | over a year ]] and is currently available [[ https://gerrit.wikimedia.org/r/c/operations/mediawiki-config/+/1196492 | on all wikis ]].
There are two known issues with specs.v0, both (ironically) related to its own OpenAPI spec:
# its OpenAPI spec [[ https://en.wikipedia.beta.wmcloud.org/w/index.php?api=specs.v0&title=Special%3ARestSandbox#/default/get_discovery | has errors ]]
# its OpenAPI spec has omissions and needs improvement. Notably some of the description strings are either missing or are placeholders
Create a specs.v1 module that resolves these issues, and begin using it.
==== Completion Criteria ====
[] The OpenAPI spec for the specs.v1 module is complete and useful, including helpful description strings
[] The specs.v1 module's OpenAPI spec loads in the REST Sandbox without error
[] Integration tests exist for the specs.v1 module
[] The specs.v1 module is enabled on all wikis
[] All REST Sandbox urls currently pointed at the specs.v0 module are instead pointed at the specs.v1 module
[] The specs.v1 module is available in the REST Sandbox (so that its own endpoints are viewable/testable)
[] The specs.v0 module is removed from the REST Sandbox
NOTE: we will not immediately deprecate or remove the specs.v0 module. It will remain callable by anyone currently using it. A separate task should be created for its deprecation/removal process. We should consider whether externally-facing communications should be part of that.
NOTE: the recently-merged ModuleManager allows enabling MW Core modules and publishing them to the REST Sandbox without config changes. This may be useful, but care should be taken to not list both the specs.v0 and specs.v1 modules in the REST Sandbox at the same time (it wouldn't cause errors, but it would be confusing).
Regarding integration tests, most of our endpoints have a snippet similar to the following:
```
openApiSpec = JSON.parse( text );
chai.use( chaiResponseValidator( openApiSpec ) );
```
This validates that the actual endpoint behavior matches the endpoint's OpenAPI spec. The current specs.v0 module integration tests do not have this.. We should try to include it in the specs.v1 integration tests. (There's also nothing wrong with spot-checking response structure, as the specs.v0 integration tests currently do.)