Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refine the description generation using comments on database objects` #43

Merged
merged 3 commits into from
Feb 22, 2024
Merged

Refine the description generation using comments on database objects` #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3081ad3
Add summary to info object
laurenceisla Feb 17, 2024
4dbad03
Add summary to operation objects (get,patch,etc.)
laurenceisla Feb 17, 2024
db7fb28
Refactor function to make it more readable
laurenceisla Feb 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions sql/main.sql
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@ $$
select oas_openapi_object(
openapi := '3.1.0',
info := oas_info_object(
title := coalesce(sd.title, 'PostgREST API'),
description := coalesce(sd.description, 'This is a dynamic API generated by PostgREST'),
title := sd.title,
summary := sd.summary,
description := sd.description,
-- The document version
version := coalesce(document_version, 'undefined')
),
Expand Down
12 changes: 8 additions & 4 deletions sql/paths.sql
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ from (
select '/' || table_name as path,
oas_path_item_object(
get :=oas_operation_object(
description := table_description,
summary := (postgrest_unfold_comment(table_description))[1],
description := (postgrest_unfold_comment(table_description))[2],
tags := array[table_name],
parameters := jsonb_agg(
oas_build_reference_to_parameters(format('rowFilter.%1$s.%2$s', table_name, column_name))
Expand Down Expand Up @@ -44,7 +45,8 @@ from (
post :=
case when insertable then
oas_operation_object(
description := table_description,
summary := (postgrest_unfold_comment(table_description))[1],
description := (postgrest_unfold_comment(table_description))[2],
tags := array[table_name],
requestBody := oas_build_reference_to_request_bodies(table_name),
parameters := jsonb_build_array(
Expand All @@ -63,7 +65,8 @@ from (
patch :=
case when updatable then
oas_operation_object(
description := table_description,
summary := (postgrest_unfold_comment(table_description))[1],
description := (postgrest_unfold_comment(table_description))[2],
tags := array[table_name],
requestBody := oas_build_reference_to_request_bodies(table_name),
parameters := jsonb_agg(
Expand Down Expand Up @@ -93,7 +96,8 @@ from (
delete :=
case when deletable then
oas_operation_object(
description := table_description,
summary := (postgrest_unfold_comment(table_description))[1],
description := (postgrest_unfold_comment(table_description))[2],
tags := array[table_name],
parameters := jsonb_agg(
oas_build_reference_to_parameters(format('rowFilter.%1$s.%2$s', table_name, column_name))
Expand Down
29 changes: 16 additions & 13 deletions sql/postgrest.sql
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ WITH
else
oas_schema_object(
description := info.description,
type := pgtype_to_oastype(info.data_type),
type := postgrest_pgtype_to_oastype(info.data_type),
format := info.data_type::text,
maxlength := info.character_maximum_length,
-- "default" := to_jsonb(info.column_default),
Expand All @@ -126,7 +126,7 @@ WITH
oas_build_reference_to_schemas(info.item_data_type)
else
oas_schema_object(
type := pgtype_to_oastype(info.item_data_type),
type := postgrest_pgtype_to_oastype(info.item_data_type),
format := info.item_data_type::text
)
end
Expand Down Expand Up @@ -408,7 +408,7 @@ WITH
else
oas_schema_object(
description := info.description,
type := pgtype_to_oastype(info.data_type),
type := postgrest_pgtype_to_oastype(info.data_type),
format := info.data_type::text,
maxlength := info.character_maximum_length,
-- "default" := to_jsonb(info.column_default),
Expand All @@ -421,7 +421,7 @@ WITH
oas_build_reference_to_schemas(info.item_data_type)
else
oas_schema_object(
type := pgtype_to_oastype(info.item_data_type),
type := postgrest_pgtype_to_oastype(info.item_data_type),
format := info.item_data_type::text
)
end
Expand Down Expand Up @@ -571,7 +571,7 @@ $$
oas_build_reference_to_schemas(info.data_type)
else
oas_schema_object(
type := pgtype_to_oastype(info.data_type),
type := postgrest_pgtype_to_oastype(info.data_type),
format := info.data_type::text,
-- TODO: take default values from pg_proc.pronargdefaults
-- "default" := to_jsonb(info.arg_default),
Expand All @@ -584,7 +584,7 @@ $$
oas_build_reference_to_schemas(info.item_data_type)
else
oas_schema_object(
type := pgtype_to_oastype(info.item_data_type),
type := postgrest_pgtype_to_oastype(info.item_data_type),
format := info.item_data_type::text
)
end
Expand Down Expand Up @@ -647,22 +647,25 @@ $$;
create or replace function postgrest_get_schema_description(schema text)
returns table (
title text,
summary text,
description text
) language sql stable as
$$
select
substr(sd.schema_desc, 0, break_position) as title,
trim(leading from substr(sd.schema_desc, break_position), '
') as description
coalesce(title, 'PostgREST API') as title,
(postgrest_unfold_comment(sum_and_desc))[1] as summary,
coalesce(
(postgrest_unfold_comment(sum_and_desc))[2],
'This is a dynamic API generated by PostgREST'
) as description
from (
select
description as schema_desc,
strpos(description, '
') as break_position
(postgrest_unfold_comment(description))[1] as title,
(postgrest_unfold_comment(description))[2] as sum_and_desc
from
pg_namespace n
left join pg_description d on d.objoid = n.oid
where
n.nspname = schema
) sd;
) _;
$$;
14 changes: 13 additions & 1 deletion sql/utils.sql
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
-- Functions that help in building the OpenAPI spec inside PostgreSQL

create or replace function pgtype_to_oastype(type text)
create or replace function postgrest_pgtype_to_oastype(type text)
returns text language sql immutable as
$$
select case when type like any(array['character', 'character varying', 'text']) then 'string'
Expand All @@ -13,6 +13,18 @@ select case when type like any(array['character', 'character varying', 'text'])
else 'string' end;
$$;

create or replace function postgrest_unfold_comment(comm text) returns text[]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a unit test for this function?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, no. In fact, I think none of the functions have unit tests.

But it makes sense for the functions inside utils.sql to have them, at least. I think they could be added in another PR. I'll open an issue for those.

language sql immutable as
$$
select array[
substr(comm, 0, break_position),
trim(leading from substr(comm, break_position), '
') -- trims newlines and empty spaces
]
from (select strpos(comm, '
') as break_position)_;
$$;

create or replace function oas_build_reference_to_schemas("schema" text)
returns jsonb language sql immutable as
$$
Expand Down
31 changes: 30 additions & 1 deletion test/expected/info.out
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,40 @@ select jsonb_pretty(postgrest_openapi_spec('{test}')->'info'->'title');
"My API title"
(1 row)

-- shows the second line of the comment on the schema as description
-- shows the second line of the comment on the schema as summary
select jsonb_pretty(postgrest_openapi_spec('{test}')->'info'->'summary');
jsonb_pretty
------------------
"My API summary"
(1 row)

-- shows the third line of the comment on the schema as description
select jsonb_pretty(postgrest_openapi_spec('{test}')->'info'->'description');
jsonb_pretty
--------------------------------------------------
"My API description\nthat spans\nmultiple lines"
(1 row)

-- shows default title when there is no comment on the schema
select jsonb_pretty(postgrest_openapi_spec('{types}')->'info'->'title');
jsonb_pretty
-----------------
"PostgREST API"
(1 row)

-- shows no summary when there is no comment on the schema
select postgrest_openapi_spec('{types}')->'info' ? 'summary';
?column?
----------
f
(1 row)


-- shows default description when there is no comment on the schema
select jsonb_pretty(postgrest_openapi_spec('{types}')->'info'->'description');
jsonb_pretty
------------------------------------------------
"This is a dynamic API generated by PostgREST"
(1 row)

-- TODO: tests for versions
Loading
Loading