interactively query api with swagger -- row filtering with .eq

[alexlenail]

Environment

• PostgreSQL version: docker, latest (11)
• PostgREST version: image: postgrest/postgrest
• Operating system: osx mojave

Description of issue

I'd like to provide the ability to users to interactively query my app's postgrest api, via swagger for example.

Say I have a column in my postgres database called project. Then postgrest's openapi will document that, and swagger allows me to fill a text input with a value I'd like to filter by, and hit "execute" which triggers the following GET:

http://0.0.0.0:3000/file?project=project1

which fails with

  "details": "unexpected \"a\" expecting \"not\" or operator (eq, gt, ...)",

When I put .eq.project1 in the text box, swagger wants to

http://0.0.0.0:3000/file?project=.eq.project1

In one respect, this is a limitation of swagger, and may not seem to belong as an issue on postgrest, but postgrest mentions swagger in the README, and in the docs:

You can use a tool like Swagger UI to create beautiful documentation from the description and to host an interactive web-based dashboard. The dashboard allows developers to make requests against a live PostgREST server, and provides guidance with request headers and example request bodies.

I'm fairly certain now the above is not true, unless there is a way to configure swagger to construct .eq-based query strings. The docs should be updated to include this configuration if it exists, or this mention of being able to use swagger interactively should be removed.

Finally, if there's other software that takes advantage of Postgrest's openapi support better than swagger, I'd love to hear about it! (and the docs should probably mention that instead of swagger). I have my eyes on ReDoc right now, but am actively looking for suggestions!

[steve-chavez]

There's definitely some limitations on what Swagger UI/OpenAPI can express regarding PostgREST capabilities.

For now I don't know of a better tool to showcase the API docs(just tried ReDoc but seems it doesn't support making requests), so perhaps what could be done is to add a note in the OpenAPI docs about the operator prefixing eq. when interacting with swagger ui. The note would contain a link to the operators list.

[steve-chavez]

Added an issue in the docs repo for this PostgREST/postgrest-docs#195.

[ronnyTodgers]

I know this is long closed, but I ran into this after wanting to easily pull together a readily explorable version of an API together. The Swagger integration put together in the docs is brilliant and it does make the job of getting the spec visible just laughably easy - it's just a shame that the wonderful website that results from it doesn't have the easy "try it out" side working.

Isn't there a really easy fix of allowing a default operator to be specified? In the case that error is thrown, the default operator is used instead. It would fix the swagger integration instantly and X=Y does tend to imply they meant equals.

[steve-chavez]

@ronnyTodgers Yes, I hear you. We have a solution for this on #1970 (comment). Let's follow up there.