Currently, the Lift Wing OpenAPI docs are stored in the inference-services repository several separate files (one for each endpoint) and combined via ref links in a top-level file. This helps make the docs easier to maintain, but it presents a few issues:

• Separate files make the docs harder to lint using the Wikimedia OpenAPI Linter (CI integration coming soon!). Since the linting rules expect some fields to be present per OpenAPI file, linting each file separately results in some errors that wouldn't apply to a single, unified file. (For example, a missing contact field.)
• Separate files make it difficult to use the OpenAPI file for client generation or similar use cases. One of the major benefits of OpenAPI is that, as a machine-readable standard, it can be used to generate client code or for other programmatic uses. With separate files, users would need to repeat their process for each file instead of being able to use one file for all endpoints.
• Fetching information from multiple files makes the MediaWiki REST Sandbox a little slow to load the first time.

Ideally, the solution would be to combine the files into a single file before they are served via the public endpoint, but I'm not sure how feasible this is considering the architecture of that endpoint. Another option is to store the OpenAPI docs as a single file in the repository and remove the per-endpoint files; this would result in a file that is probably ~2,000 lines long at least.

Happy to discuss these options and tradeoffs, and work on a solution that works best for inference-services maintainers!