RESTbase supports self-documentation based on OpenAPI specifications. The REST framework built into core should support the same, for feature parity with RESTbase and the action API.
Description
Description
Details
Details
| Subject | Repo | Branch | Lines +/- | |
|---|---|---|---|---|
| Generate request body specs from param settings. | mediawiki/core | master | +566 -72 | |
| Re-apply "REST: Emit swagger spec" | mediawiki/core | master | +1 K -12 | |
| REST: Emit swagger spec | mediawiki/core | master | +804 -12 |
Event Timeline
Comment Actions
Change 860691 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):
[mediawiki/core@master] WIP: REST: emit swagger spec
Comment Actions
Would love to see all of our REST APIs specify deterministic output types, ideally following some of the same schema guidelines used by Event Platform. This would allow us to use REST API endpoints as 'lookup tables', and allow us to join them and other datasets with SQL.
Comment Actions
@daniel should we have a separate task for REST Gateway + Migrated Services?
I believe that for services migrated away from RESTBase into the new REST Gateway, OpenAPI specs could be easier maintained and routed by each service, but we also had a conversation about taking advantage of all the documentation lying in RESTBase Today and maybe using the RESTBase repo just for that in the short term, is that a fair assumption?
Comment Actions
I'm really excited about this! Would it be possible to expand the description of this task to describe how the OpenAPI spec will be generated and where it will pull information from? I'm having trouble following the file changes in patch, and I'd be interested in providing feedback. Having the description of the OpenAPI system will also help document it once it's merged. If it's helpful, I've listed the elements of documenting a REST endpoint on this wiki page.
Comment Actions
Change 979705 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):
[mediawiki/core@master] Re-apply "REST: Emit swagger spec"
Comment Actions
Change 979705 merged by jenkins-bot:
[mediawiki/core@master] Re-apply "REST: Emit swagger spec"
Comment Actions
I think this is done. If T362480: Introduces support for modules into the REST API framework continues the direction it is currently trending and is merged, then it changes some things with the MW REST API swagger spec that we'll want to address. But that would be more properly done under a new task.
Comment Actions
Change #1017343 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):
[mediawiki/core@master] Generate request body specs from param settings.