Add summary to the info object

[laurenceisla]

In OAS 2.0, only the title and description are specified. Maybe a comment on the schema could be interpreted as:

'title
summary
description line 1
description line 2..'

Currently, it only detects title and description.

[wayland]

It seemed to me like the Haskell code took the first line of the COMMENT as the summary, and the rest as the description. That's the model that I've used in my code.

[laurenceisla]

Ah, only the title and description are specified in the code:

https://github.com/PostgREST/postgrest/blob/ed90774f53b8a1c6386c55dfaf13a8cf1004a683/src/PostgREST/Response/OpenAPI.hs#L400-L401

Additionally, OAS 3.1 also allows a summary.

[wayland]

Hmm. In order to make it readable, maybe we should use the format:

Title: <title>
Summary: <summary>

<description>

Much like an e-mail or web request, with headers, then blank line, then body. Before using, we lowercase the headers and match them against the allowed list (just title and summary, in this case).

Edit: As an additional bonus, we could also support, for the Schema description, a "Version", which would be the OpenAPI Document Version

[laurenceisla]

In #43, I decided to use the original format I proposed to separate Title, Summary and Description. I think it's more convenient to write for users. For readability they can also be separated by extra new lines, e.g.:

'title

summary

description line 1
description line 2..'

As an additional bonus, we could also support, for the Schema description, a "Version", which would be the OpenAPI Document Version

I'm liking this idea. But I'm not sure where it should go... maybe it could be alongside the title:

'My API title - 1.0.0
...'

The separator could be different from -. Or it could be at the start too.

'1.0.0
My API title
...'