Page MenuHomePhabricator

REST framework: Add support for outputting an OpenAPI (swagger) spec
Closed, ResolvedPublic

Description

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.

Related Objects

Event Timeline

Change 860691 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] WIP: REST: emit swagger spec

https://gerrit.wikimedia.org/r/860691

daniel raised the priority of this task from Low to Medium.Jun 5 2023, 6:11 PM
daniel moved this task from PCS Service Pile to Infrastructure Pile on the RESTBase Sunsetting board.

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.

@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?

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.

Change 860691 merged by jenkins-bot:

[mediawiki/core@master] REST: Emit swagger spec

https://gerrit.wikimedia.org/r/860691

Change 979705 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] Re-apply "REST: Emit swagger spec"

https://gerrit.wikimedia.org/r/979705

Change 979705 merged by jenkins-bot:

[mediawiki/core@master] Re-apply "REST: Emit swagger spec"

https://gerrit.wikimedia.org/r/979705

BPirkle claimed this task.

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.