OpenAPI
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 db-anon-role if no JWT is sent). If you need to show all the endpoints disregarding the role’s permissions, set the openapi-mode config to ignore-privileges
.
For extra customization, the OpenAPI output contains a “description” field for every SQL comment on any database object. For instance,
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:
COMMENT ON TABLE entities IS
$$Entities summary
Entities description that
spans
multiple lines$$;
Similarly, you can override the API title by commenting the schema.
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 openapi-security-active configuration to true
.
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.
Important
The OpenAPI information can go out of date as the schema changes under a running server. See Schema Cache Reloading.
Overriding Full OpenAPI Response
You can override the whole default response with a function result. To do this, set the function on db-root-spec.
db-root-spec = "root"
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;
curl http://localhost:3000
HTTP/1.1 200 OK
{
"swagger": "2.0",
"info":{
"title":"Overridden",
"description":"This is a my own API"
}
}