Our current Mediawiki APIs on-wiki docs at https://www.mediawiki.org/wiki/API:REST_API - does not have an OpenAPI section.
We should add this section to make the API easier to understand, and much more attractive to internal developers - while reducing long-term documentation and support costs
I think a full section is unnecessary. OpenAPI specs are used for interactive documentation, as hosted and presented through the REST Sandbox. The REST Sandbox also provides a link to download the spec for each module within that context. That should be sufficient at this time.
The alternative would be that we have a section where we present links to download specs for each module under the scope of a given API, which would then transition to be more of an API catalogue (which would also likely ultimately direct to a sandbox solution where dedicated spec presentation would be a bit redundant).
Let me know if you disagree or had something else in mind. Happy to discuss, but there are fairly well established patterns in this space for spec retrieval within the context of reference docs and/or a sandbox without direct presentation or a separate list of download links or whatever.
Atieno can correct me if I'm wrong, but I think the idea was for something directed at MW REST developers, not callers, to help developers know how to add OpenAPI-related info to their code.
Further to that, we currently have this page, which has basic developer-facing documentation for adding endpoints. We should dramatically improve the quality of all these docs, and I know work is in progress on that front. In the meantime, it wouldn't hurt to have at least a little bit of information on a page like this.
I also notice that the top-level documentation page for MW REST links to the above page, but with the text "Access endpoints created by MediaWiki extensions". That's really not what the page being linked to is about, so we should consider adjusting that as well.
@BPirkle the suggestion is explicitly for external developers:
We should add this section to make the API easier to understand, and much more attractive to external developers - while reducing long-term documentation and support costs
I agree that we should improve our docs for internal developers/API builders, but that's not what this ticket is saying.
Hello all.
@apaskulin @HCoplin-WMF @BPirkle
This ticket is a follow up from T412668 that has a Documentation clearly explains how to declare and consume header information in specs task. So looking at https://www.mediawiki.org/wiki/API:REST_API which is the REST_API doc if were to have "English text" for the request and response headers work it would make sense to have it within an OpenAPI section and not hanging on it's own. That's the thought behind this ticket.
If a full section is an unnecessary I agree on the alternatives of having downloadable links per module per API.
I have corrected the "external developers" bit I believe it generally implies developers outside the Foundation and not really developers outside the teams working on the specs.