diff --git a/api.rst b/api.rst index ae9006734..735aa2940 100644 --- a/api.rst +++ b/api.rst @@ -1410,7 +1410,13 @@ This follows the same rules as :ref:`binary_output`. OpenAPI Support =============== -Every API hosted by PostgREST automatically serves a full `OpenAPI `_ description on the root path. This provides a list of all endpoints(tables, foreign tables, views, functions), along with supported HTTP verbs and example payloads. For extra customization, the OpenAPI output contains a "description" field for every `SQL comment `_ on any database object. For instance, +Every API hosted by PostgREST automatically serves a full `OpenAPI `_ description on the root path. This provides a list of all endpoints (tables, foreign tables, views, functions), along with supported HTTP verbs and example payloads. + +.. note:: + + By default, this output depends on the permissions of the role that is contained in the JWT role claim (or the :ref:`db-anon-role` if no JWT is sent). If you need to show all the endpoints disregarding the role's permissions, set the :ref:`openapi-mode` config to :code:`ignore_privileges`. + +For extra customization, the OpenAPI output contains a "description" field for every `SQL comment `_ on any database object. For instance, .. code-block:: sql diff --git a/configuration.rst b/configuration.rst index b7f4e475d..960002b67 100644 --- a/configuration.rst +++ b/configuration.rst @@ -30,12 +30,12 @@ The user specified in the db-uri is also known as the authenticator role. For mo Here is the full list of configuration parameters. -======================== ======= ========= ======== -Name Type Default Required -======================== ======= ========= ======== -db-uri String Y -db-schema String Y -db-anon-role String Y +======================== ======= ================= ======== +Name Type Default Required +======================== ======= ================= ======== +db-uri String Y +db-schema String Y +db-anon-role String Y db-pool Int 10 db-pool-timeout Int 10 db-extra-search-path String public @@ -43,6 +43,7 @@ server-host String !4 server-port Int 3000 server-unix-socket String server-unix-socket-mode String 660 +openapi-mode String follow-privileges openapi-server-proxy-uri String jwt-secret String jwt-aud String @@ -52,7 +53,7 @@ pre-request String app.settings.* String role-claim-key String .role raw-media-types String -======================== ======= ========= ======== +======================== ======= ================= ======== .. _db-uri: @@ -175,6 +176,27 @@ server-unix-socket-mode server-unix-socket-mode = "660" +.. _openapi-mode: + +openapi-mode +------------ + + Specifies how the OpenAPI output should be displayed: + + .. code:: bash + + # Follows the privileges of the JWT role claim (or from db-anon-role if the JWT is not sent) + # Shows information depending on the permissions that the role making the request has + openapi-mode = "follow-privileges" + + # Ignores the privileges of the JWT role claim (or from db-anon-role if the JWT is not sent) + # Shows all the exposed information, regardless of the permissions that the role making the request has + openapi-mode = "ignore-privileges" + + # Disables the OpenApi output altogether. + # Throws a `404 Not Found` error when accessing the API root path + openapi-mode = "disabled" + .. _openapi-server-proxy-uri: openapi-server-proxy-uri diff --git a/releases/upcoming.rst b/releases/upcoming.rst index a3e10dc9f..398370f05 100644 --- a/releases/upcoming.rst +++ b/releases/upcoming.rst @@ -16,6 +16,9 @@ Added * Allow :ref:`s_procs_variadic`. |br| -- `@wolfgangwalther `_ +* Config options for showing a full OpenAPI output regardless of the JWT role privileges and for disabling it altogether. See :ref:`openapi-mode`. + |br| -- `@steve-chavez `_ + * Documentation improvements + Added the :ref:`OPTIONS requests ` section.