99 lines
3.2 KiB
ReStructuredText
99 lines
3.2 KiB
ReStructuredText
.. _open-api:
|
|
|
|
OpenAPI
|
|
=======
|
|
|
|
PostgREST automatically serves a full `OpenAPI <https://www.openapis.org/>`_ 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 <https://www.postgresql.org/docs/current/sql-comment.html>`_ on any database object. For instance,
|
|
|
|
.. code-block:: postgres
|
|
|
|
COMMENT ON SCHEMA mammals IS
|
|
'A warm-blooded vertebrate animal of a class that is distinguished by the secretion of milk by females for the nourishment of the young';
|
|
|
|
COMMENT ON TABLE monotremes IS
|
|
'Freakish mammals lay the best eggs for breakfast';
|
|
|
|
COMMENT ON COLUMN monotremes.has_venomous_claw IS
|
|
'Sometimes breakfast is not worth it';
|
|
|
|
These unsavory comments will appear in the generated JSON as the fields, ``info.description``, ``definitions.monotremes.description`` and ``definitions.monotremes.properties.has_venomous_claw.description``.
|
|
|
|
Also if you wish to generate a ``summary`` field you can do it by having a multiple line comment, the ``summary`` will be the first line and the ``description`` the lines that follow it:
|
|
|
|
.. code-block:: postgres
|
|
|
|
COMMENT ON TABLE entities IS
|
|
$$Entities summary
|
|
|
|
Entities description that
|
|
spans
|
|
multiple lines$$;
|
|
|
|
Similarly, you can override the API title by commenting the schema.
|
|
|
|
.. code-block:: postgres
|
|
|
|
COMMENT ON SCHEMA api IS
|
|
$$FooBar API
|
|
|
|
A RESTful API that serves FooBar data.$$;
|
|
|
|
If you need to include the ``security`` and ``securityDefinitions`` options, set the :ref:`openapi-security-active` configuration to ``true``.
|
|
|
|
You can use a tool like `Swagger UI <https://swagger.io/tools/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.
|
|
|
|
.. important::
|
|
|
|
The OpenAPI information can go out of date as the schema changes under a running server. See :ref:`schema_reloading`.
|
|
|
|
.. _override_openapi:
|
|
|
|
Overriding Full OpenAPI Response
|
|
--------------------------------
|
|
|
|
You can override the whole default response with a function result. To do this, set the function on :ref:`db-root-spec`.
|
|
|
|
.. code:: bash
|
|
|
|
db-root-spec = "root"
|
|
|
|
.. code:: postgres
|
|
|
|
create or replace function root() returns json as $_$
|
|
declare
|
|
openapi json = $$
|
|
{
|
|
"swagger": "2.0",
|
|
"info":{
|
|
"title":"Overridden",
|
|
"description":"This is a my own API"
|
|
}
|
|
}
|
|
$$;
|
|
begin
|
|
return openapi;
|
|
end
|
|
$_$ language plpgsql;
|
|
|
|
.. code-block:: bash
|
|
|
|
curl http://localhost:3000
|
|
|
|
.. code-block:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
|
|
{
|
|
"swagger": "2.0",
|
|
"info":{
|
|
"title":"Overridden",
|
|
"description":"This is a my own API"
|
|
}
|
|
}
|