From a3d87edda35c585b82c2d1a65ed2d5cf2f51b093 Mon Sep 17 00:00:00 2001 From: Joe Nelson Date: Sun, 8 Oct 2017 12:38:46 -0500 Subject: [PATCH] Explain how sql comments appear in the openapi output (#111) --- api.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/api.rst b/api.rst index c05547b07..2a4480f93 100644 --- a/api.rst +++ b/api.rst @@ -678,9 +678,19 @@ To delete rows in a table, use the DELETE verb plus :ref:`h_filter`. For instanc OpenAPI Support =============== -Every API hosted by PostgREST automatically serves a full `OpenAPI `_ description on the root path. This provides a list of all endpoints, along with supported HTTP verbs and example payloads. +Every API hosted by PostgREST automatically serves a full `OpenAPI `_ description on the root path. This provides a list of all endpoints, along with supported HTTP verbs and example payloads. For extra customization, the OpenAPI output contains a "description" field for every `SQL comment `_ on a table, column, or function. For instance, -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, provides guidance with request headers and example request bodies. +.. code-block:: sql + + 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 ``definitions.monotremes.description`` and ``definitions.monotremes.properties.has_venomous_claw.description``. + +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. .. note::