Repeated "Prefer" header overrides the previous one in SwaggerUI

[laurenceisla]

I had the idea to repeat the Prefer header for each preference that PostgREST has (count, tx, etc.). This would be useful to allow more than one Prefer Header at a time (which is not possible right now in the core repo).

But in SwaggerUI, the other Prefer headers are overridden and have the same value as the first one (since they all have the same name: Prefer). A solution would be to just add the valid transactions in the description e.g. "Valid values are: tx=commit, return=minimal, ..." or find if it's possible to allow many enums (couldn't find a way yet).

This is the relevant function:

postgrest-openapi/sql/postgrest.sql

Line 615 in 81f5b64

create or replace function postgrest_get_headers ()

[steve-chavez]

Can anyOf work for this? https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

Also relevant: OAI/OpenAPI-Specification#2109

[laurenceisla]

@steve-chavez

After doing some experiments, using an array type with anyOf and different values seems to be a valid approach. But I kinda like the second example more: it uses a JSON object to insert values and serializes it to key=value pairs in the CURL execution. E.g.

{
  "count": "exact",
  "return": "representation"
}

curl ... \
  -H `Prefer: count=exact, return=representation`

The advantage over anyOf is that it validates the type of the value, e.g. it does not allow count=123 or max-affected=string. What bothers me is that the Swagger Editor does not reference the Schema, which would be useful to get all the possible values, and it does not validate the enum values for each property (this is also a problem for anyOf). Maybe it's a current limitation of the Swagger Editor and enums, because I also tested Regex using the pattern property and it validates it properly (it could be used as an alternative).

[laurenceisla]

... the Swagger Editor does not reference the Schema, which would be useful to get all the possible values, and it does not validate the enum values for each property (this is also a problem for anyOf)

It seems that it behaves differently for each UI. Redocly listed the available values and examples nicely, although I couldn't test the CURL generation since it doesn't have that feature. In Rapidoc, it also lists the schema but does not generate the CURL example correctly (ignores the header).

I'll fix and implement it that way to avoid blockers. User feedback may be needed here.

Edit: Just noticed that it still needs the use of allOf if we want to reuse prefers amongst the different methods. That is, define a schema for each preference and join them using allOf for each method, e.g. prefer_get has schema: allOf: prefer_count,prefer_timezone,etc.