The AQS 2.0 services will generate one OpenAPI specification per service. The resulting specs will be published to each of the code repositories at docs/swagger.json. To make these docs publicly accessible, we need to define a strategy to:
1. Serve the spec file
Serve each specs so that it is accessible via a public URL. (For example, at https://api.wikimedia.org/pageviews/api-spec.json) Currently, the OpenAPI spec is stored in the git repo of each service.
Alternatively, we could do in-memory generation at runtime and emit caching headers such that we effectively store the generated file in Varnish rather than it being a deployed file, but we haven't investigated this option.
2. Serve the HTML docs
Serve an HTML view of the spec using RapiDoc as shown in the example below. (For example, at https://api.wikimedia.org/pageviews/api-docs). This doesn't necessarily have to be handled by the service. As long as the raw spec file is publicly available, a minimum viable option could be to create a subpage of https://api-spec-reader.toolforge.org/ that preloads a given spec.
RapiDoc example
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
</head>
<body>
<rapi-doc
spec-url = "ADD SPEC URL HERE"
theme = "dark"
schema-style="table"
fill-request-fields-with-example="false"
primary-color="#049DFF"
font-size="large"
>
</rapi-doc>
</body>
</html>