Recommended approach for enhancing generated OpenAPI documentation

[kjcsb1]

PostgREST 12.2

As recommended, we expose views (not tables) through PostgREST and those are included in the automatically-generated OpenAPI documentation.

I would like to:

1. include view-level and column-level comments. Comments added to tables (as recommended in the documentation ) don't appear in the generated OpenAPI file
2. order and group the generated paths. The generated OpenAPI file doesn't appear to be in any particular or admin-configurable order

What are the recommendations for generating documentation? One option would be to maintain a list of views in a table containing metadata. We could then write a script to retrieve the metadata and enhance the generated file.

Any suggestions appreciated.

[wolfgangwalther]

include view-level and column-level comments.

I just tested and comments on views and columns of views appear in the OpenAPI output:

COMMENT ON VIEW <schema>.<view> IS 'hello';
COMMENT ON COLUMN <schem>.<view>.<column> IS 'world';

order and group the generated paths.

That's currently not possible.

[kjcsb1]

Well that's embarrassing! Updated the docs to make that clear.

[steve-chavez]

order and group the generated paths.
That's currently not possible.

@laurenceisla Is that possible to do in a standard way? (Maybe for https://github.com/PostgREST/postgrest-openapi)