diff --git a/CHANGELOG.md b/CHANGELOG.md index cf68b750c..2e995d3d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ This project adheres to [Semantic Versioning](http://semver.org/). - #1145, Add materialized view columns to OpenAPI output - @steve-chavez - #709, Allow embedding on views with subselects/CTE - @steve-chavez - #1148, OpenAPI: add `required` section for the non-nullable columns - @laughedelic +- #1158, Add summary to OpenAPI doc for RPC functions - @mdr1384 ### Fixed diff --git a/src/PostgREST/OpenAPI.hs b/src/PostgREST/OpenAPI.hs index a199fd418..20ffda41d 100644 --- a/src/PostgREST/OpenAPI.hs +++ b/src/PostgREST/OpenAPI.hs @@ -223,8 +223,13 @@ makePathItem (t, cs, _) = ("/" ++ unpack tn, p $ tableInsertable t) makeProcPathItem :: ProcDescription -> (FilePath, PathItem) makeProcPathItem pd = ("/rpc/" ++ toS (pdName pd), pe) where + -- Use first line of proc description as summary; rest as description (if present) + -- We strip leading newlines from description so that users can include a blank line between summary and description + (pSum, pDesc) = fmap fst &&& fmap (dropWhile (=='\n') . snd) $ + breakOn "\n" <$> pdDescription pd postOp = (mempty :: Operation) - & description .~ pdDescription pd + & summary .~ pSum + & description .~ mfilter (/="") pDesc & parameters .~ makeProcParam pd & tags .~ Set.fromList ["(rpc) " <> pdName pd] & produces ?~ makeMimeList [CTApplicationJSON, CTSingularJSON] diff --git a/test/Feature/StructureSpec.hs b/test/Feature/StructureSpec.hs index 82acd8b4d..0427b0f5a 100644 --- a/test/Feature/StructureSpec.hs +++ b/test/Feature/StructureSpec.hs @@ -221,13 +221,20 @@ spec = do describe "RPC" $ do - it "includes body schema for arguments" $ do + it "includes function summary/description and body schema for arguments" $ do r <- simpleBody <$> get "/" - let args = r ^? key "paths" . key "/rpc/varied_arguments" - . key "post" . key "parameters" - . nth 0 . key "schema" - liftIO $ + let method s = key "paths" . key "/rpc/varied_arguments" . key s + args = r ^? method "post" . key "parameters" . nth 0 . key "schema" + summary = r ^? method "post" . key "summary" + description = r ^? method "post" . key "description" + + liftIO $ do + + summary `shouldBe` Just "An RPC function" + + description `shouldBe` Just "Just a test for RPC function arguments" + args `shouldBe` Just [aesonQQ| { @@ -269,7 +276,8 @@ spec = do "type": "integer" } }, - "type": "object" + "type": "object", + "description": "An RPC function\n\nJust a test for RPC function arguments" } |] diff --git a/test/fixtures/schema.sql b/test/fixtures/schema.sql index ff7fd2456..2055d1ce2 100755 --- a/test/fixtures/schema.sql +++ b/test/fixtures/schema.sql @@ -222,6 +222,10 @@ AS $_$ SELECT 'Hi'::text; $_$; +COMMENT ON FUNCTION varied_arguments(double precision, character varying, boolean, date, money, enum_menagerie_type, integer) IS +$_$An RPC function + +Just a test for RPC function arguments$_$; -- -- Name: jwt_test(); Type: FUNCTION; Schema: test; Owner: -