Split off openapi into postgrest-contrib

[wolfgangwalther]

Problem

OpenAPI support is not up to date: We support v2, but v3 is out there for some years now (#932). Currently we have 26 issues open that are tagged "OpenAPI".

I'm sure some of those issues are not that hard to solve in theory. I feel like having the OpenAPI code in haskell is quite a hurdle for community contributions, though. The majority of our users probably does not know haskell at all - but would be able to make contributions in SQL.

Test coverage seems to be quite low for that area, too. I recently played a bit with #1653 - but was surprised to see that I didn't get any failing tests after changing some things.

Suggestion

I suggest to split off all the openapi related code. Remove it from core postgrest, put it in a separate (still official) postgrest-contrib repo and turn all the code into SQL. We already have the db-root-spec config option, to be able to use it.

Then we ship PostgREST without openapi support at all. In the docs we are very clear about how to add openapi support from our "official extension". It's basically just running a SQL script to create the function(s) + setting the config option. Without this config option, the root endpoint does not return anything (or maybe a hint on how to add openapi support, if that's better).

I see the following advantages of this:

• Less complex codebase for postgrest core
• Fewer stuff to load with the schema cache, might make startup faster
• Hopefully increased community contributions for the openapi parts, because of lower hurdles to do so
• Ability to provide OpenAPI v3 support in addition to v2 without breaking changes: Users are able to choose which set of functions to install.
• Ability to disable OpenAPI output by not providing a db-root-spec config at all
• Ability to extend / change the output specifically for a single project (currently root-spec is available as well, but you would still have to reproduce the whole code in SQL first)
• Ability to add root endpoint filtering (#1421) by treating the db-root-spec mostly like a regular RPC (with some small tweaks, it should be able to add something powerful)

The postgrest-contrib repo could have other SQL-only stuff, too. E.g. #1690 and other SQL snippets we are suggesting in the docs right now. We can have several distribution formats for this repo, e.g. as pg extension or just as one big SQL file (for cloud hosted pg servers). Users can install just some parts of this or everything - and then just enable those functions in the postgrest configuration.

Having this in a separate repo should make it a bit easier to track on the issue tracker. Also, while some SQL parts might be postgrest-version dependent, most parts while likely be usable across more versions. Having a different repo (and multi-version compatibility in mind) should make it easier to perform major version upgrades of postgrest - without the need to update the SQL code at the same time.

The biggest challenge I see will be making that openapi output reflect what PostgREST really does. Parts of the output are only reflecting the database schema and are unrelated to PostgREST itself (think db comments as an example), but others (think embedding opportunities - if those could be part of the openapi output, that would be great) are heavily dependent on PostgREST itself. To sync this, we could pass (a part of) the schema cache via JSON parameter to the openapi function, to make it aware of what PostgREST knows about the database. We'd still have to work out the details, of course.