packages feed

relay-pagination-servant 0.1.1.2 → 0.2.0.0

raw patch · 10 files changed

+783/−124 lines, 10 filesdep ~relay-paginationPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: relay-pagination

API changes (from Hackage documentation)

+ Relay.Pagination.Servant.OpenApi: instance Data.OpenApi.Internal.Schema.ToSchema a => Data.OpenApi.Internal.Schema.ToSchema (Relay.Pagination.Connection.CountedConnection a)

Files

CHANGELOG.md view
@@ -2,6 +2,16 @@  Versioning follows the [Haskell Package Versioning Policy](https://pvp.haskell.org/). +## 0.2.0.0 — 2026-11-18++### Added++- Declare `CountedConnection` as the success response to require an integer `totalCount` with minimum zero in OpenAPI. The uncounted schema remains byte-identical.++### Other changes++- Align the core dependency with 0.2.0.0. Code that constructs `Connection` directly needs `totalCount = Nothing` to keep the uncounted response.+ ## 0.1.1.2 — 2026-10-06  ### Fixed
+ demo/CountedToyApi.hs view
@@ -0,0 +1,59 @@+-- | A second toy API for testing counted and uncounted routes together.+module CountedToyApi+  ( CountedToyRoutes (..),+    CountedToyResult (..),+    countedToyApi,+    countedToyApp,+  )+where++import Data.Proxy (Proxy (..))+import Data.SOP (I (..), NS (..))+import GHC.Generics (Generic)+import Network.Wai (Application)+import Relay.Pagination (CountedConnection, countedConnection)+import Relay.Pagination.Servant (RelayPage, RelayPageError)+import Servant (serve)+import Servant.API (JSON, NamedRoutes, StdMethod (GET), (:-), (:>))+import Servant.API.MultiVerb (AsUnion (..), MultiVerb, Respond)+import ToyApi (Item, ToyItemsEndpoint, ToyRoutes (..), echoPage, toyServer)++type CountedToyResponses =+  '[ Respond 200 "Counted page of items" (CountedConnection Item),+     Respond 400 "Invalid pagination" RelayPageError+   ]++data CountedToyResult+  = CountedToyOk !(CountedConnection Item)+  | CountedToyBadRequest !RelayPageError+  deriving stock (Eq, Show)++instance AsUnion CountedToyResponses CountedToyResult where+  toUnion = \case+    CountedToyOk page -> Z (I page)+    CountedToyBadRequest err -> S (Z (I err))+  fromUnion = \case+    Z (I page) -> CountedToyOk page+    S (Z (I err)) -> CountedToyBadRequest err+    S (S impossible) -> case impossible of {}++data CountedToyRoutes mode = CountedToyRoutes+  { uncountedItems :: mode :- ToyItemsEndpoint,+    countedItems ::+      mode+        :- "counted-items"+          :> RelayPage 10 100+          :> MultiVerb 'GET '[JSON] CountedToyResponses CountedToyResult+  }+  deriving stock (Generic)++countedToyApi :: Proxy (NamedRoutes CountedToyRoutes)+countedToyApi = Proxy++countedToyApp :: Application+countedToyApp =+  serve countedToyApi $+    CountedToyRoutes+      { uncountedItems = items toyServer,+        countedItems = pure . CountedToyOk . countedConnection 42 . echoPage+      }
demo/OpenApiMain.hs view
@@ -1,6 +1,6 @@ -- | Writes the checked OpenAPI 3.1 artifact. This executable is the __only__--- thing allowed to write @relay-pagination-servant/test/golden/toy-openapi.json@;--- the test suite compares the checked bytes read-only (no @--accept@ mode).+-- thing allowed to write the toy OpenAPI goldens. The test suite compares+-- the checked bytes read-only. -- -- Run from the repository root: --@@ -8,11 +8,14 @@ module Main (main) where  import Data.ByteString.Lazy qualified as LBS-import ToyOpenApi (renderToyOpenApi)+import ToyOpenApi (renderCountedToyOpenApi, renderToyOpenApi)  main :: IO () main = do-  LBS.writeFile artifactPath renderToyOpenApi-  putStrLn ("wrote " <> artifactPath)+  writeGolden "toy-openapi.json" renderToyOpenApi+  writeGolden "toy-counted-openapi.json" renderCountedToyOpenApi   where-    artifactPath = "relay-pagination-servant/test/golden/toy-openapi.json"+    writeGolden file bytes = do+      let artifactPath = "relay-pagination-servant/test/golden/" <> file+      LBS.writeFile artifactPath bytes+      putStrLn ("wrote " <> artifactPath)
demo/ToyApi.hs view
@@ -17,6 +17,7 @@     toyServer,     toyApp,     toyCursor,+    echoPage,   ) where @@ -85,25 +86,27 @@ toyCursor = Cursor "ZWRnZS0x"  toyServer :: ToyRoutes (AsServerT Handler)-toyServer = ToyRoutes {items = serveItems}+toyServer = ToyRoutes {items = pure . ToyPageOk . echoPage}++echoPage :: PageRequest -> Connection Item+echoPage pr =+  Connection+    { edges =+        [ Edge+            { node = Item {itemId = pageSize pr, itemName = directionText (direction pr)},+              cursor = toyCursor+            }+        ],+      pageInfo =+        PageInfo+          { hasNextPage = False,+            hasPreviousPage = False,+            startCursor = Just toyCursor,+            endCursor = Just toyCursor+          },+      totalCount = Nothing+    }   where-    serveItems pr =-      pure . ToyPageOk $-        Connection-          { edges =-              [ Edge-                  { node = Item {itemId = pageSize pr, itemName = directionText (direction pr)},-                    cursor = toyCursor-                  }-              ],-            pageInfo =-              PageInfo-                { hasNextPage = False,-                  hasPreviousPage = False,-                  startCursor = Just toyCursor,-                  endCursor = Just toyCursor-                }-          }     directionText Forward = "forward" :: Text     directionText Backward = "backward" 
demo/ToyOpenApi.hs view
@@ -5,13 +5,16 @@ module ToyOpenApi   ( toyOpenApi,     renderToyOpenApi,+    countedToyOpenApi,+    renderCountedToyOpenApi,   ) where -import Control.Lens ((&), (?~))+import Control.Lens (ix, (&), (?~), _Just)+import CountedToyApi (countedToyApi) import Data.Aeson.Encode.Pretty (Config (..), defConfig, encodePretty') import Data.ByteString.Lazy (ByteString)-import Data.OpenApi (OpenApi, allOperations, operationId)+import Data.OpenApi (OpenApi, allOperations, get, operationId, paths) import Relay.Pagination.Servant.OpenApi () import Servant.OpenApi (toOpenApi) import ToyApi (toyApi)@@ -24,4 +27,16 @@ -- | Byte-stable output for the checked artifact and the drift test: sorted -- keys, one trailing newline. renderToyOpenApi :: ByteString-renderToyOpenApi = encodePretty' defConfig {confCompare = compare} toyOpenApi <> "\n"+renderToyOpenApi = render toyOpenApi++countedToyOpenApi :: OpenApi+countedToyOpenApi =+  toOpenApi countedToyApi+    & paths . ix "/items" . get . _Just . operationId ?~ "getItems"+    & paths . ix "/counted-items" . get . _Just . operationId ?~ "getCountedItems"++renderCountedToyOpenApi :: ByteString+renderCountedToyOpenApi = render countedToyOpenApi++render :: OpenApi -> ByteString+render doc = encodePretty' defConfig {confCompare = compare} doc <> "\n"
relay-pagination-servant.cabal view
@@ -1,6 +1,6 @@-cabal-version:   3.0-name:            relay-pagination-servant-version:         0.1.1.2+cabal-version: 3.0+name: relay-pagination-servant+version: 0.2.0.0 synopsis:   RelayPage servant combinator for Relay-style cursor pagination @@ -11,26 +11,32 @@   Ships HasServer, HasClient, and HasLink instances plus OpenAPI 3.1   documentation support via openapi-hs and servant-openapi-hs. -license:         BSD-3-Clause-license-file:    LICENSE-author:          Nadeem Bitar-maintainer:      Nadeem Bitar-category:        Web, Servant-build-type:      Simple+license: BSD-3-Clause+license-file: LICENSE+author: Nadeem Bitar+maintainer: Nadeem Bitar+category: Web, Servant+build-type: Simple extra-doc-files: CHANGELOG.md+extra-source-files: test/golden/*.json  source-repository head-  type:     git+  type: git   location: https://github.com/shinzui/relay-pagination  common warnings   ghc-options:-    -Wall -Wcompat -Widentities -Wincomplete-record-updates-    -Wincomplete-uni-patterns -Wredundant-constraints -Wunused-packages+    -Wall+    -Wcompat+    -Widentities+    -Wincomplete-record-updates+    -Wincomplete-uni-patterns+    -Wredundant-constraints+    -Wunused-packages  common lang-  import:             warnings-  default-language:   GHC2024+  import: warnings+  default-language: GHC2024   default-extensions:     DeriveAnyClass     DuplicateRecordFields@@ -38,103 +44,107 @@     OverloadedStrings  library-  import:          lang-  hs-source-dirs:  src+  import: lang+  hs-source-dirs: src   exposed-modules:     Relay.Pagination.Servant     Relay.Pagination.Servant.OpenApi    build-depends:-    , aeson                >=2.2      && <2.3-    , base                 >=4.21     && <5-    , http-api-data        >=0.6      && <0.8-    , http-types           >=0.12     && <0.13-    , lens                 >=5.3.3    && <5.4-    , openapi-hs           >=5.0      && <5.1-    , relay-pagination     ^>=0.1.1.2-    , servant              >=0.20.3   && <0.21-    , servant-client-core  >=0.20.3   && <0.21-    , servant-openapi-hs   >=5.1      && <5.2-    , servant-server       >=0.20.3   && <0.21-    , text                 >=2.0      && <2.2-    , wai                  >=3.2      && <3.3+    aeson >=2.2 && <2.3,+    base >=4.21 && <5,+    http-api-data >=0.6 && <0.8,+    http-types >=0.12 && <0.13,+    lens >=5.3.3 && <5.4,+    openapi-hs >=5.0 && <5.1,+    relay-pagination ^>=0.2.0.0,+    servant >=0.20.3 && <0.21,+    servant-client-core >=0.20.3 && <0.21,+    servant-openapi-hs >=5.1 && <5.2,+    servant-server >=0.20.3 && <0.21,+    text >=2.0 && <2.2,+    wai >=3.2 && <3.3,  test-suite relay-pagination-servant-test-  import:         lang-  type:           exitcode-stdio-1.0-  hs-source-dirs: test demo-  main-is:        Main.hs+  import: lang+  type: exitcode-stdio-1.0+  hs-source-dirs:+    test+    demo++  main-is: Main.hs   other-modules:+    CountedToyApi     ToyApi     ToyOpenApi    -- warp requires the threaded RTS (its TimerManager will not start without it)-  ghc-options:    -threaded+  ghc-options: -threaded   build-depends:-    , aeson-    , aeson-pretty              >=0.8      && <0.9-    , base-    , bytestring                >=0.11     && <0.13-    , http-api-data-    , http-client               >=0.7      && <0.8-    , http-types-    , lens-    , openapi-hs-    , relay-pagination          ^>=0.1.1.2-    , relay-pagination-servant-    , servant-    , servant-client            >=0.20.3   && <0.21-    , servant-client-core-    , servant-openapi-hs-    , servant-server-    , sop-core                  >=0.5      && <0.6-    , tasty                     >=1.4      && <1.6-    , tasty-hunit               >=0.10     && <0.11-    , text-    , wai-    , warp                      >=3.3      && <3.5+    aeson,+    aeson-pretty >=0.8 && <0.9,+    base,+    bytestring >=0.11 && <0.13,+    http-api-data,+    http-client >=0.7 && <0.8,+    http-types,+    lens,+    openapi-hs,+    relay-pagination ^>=0.2.0.0,+    relay-pagination-servant,+    servant,+    servant-client >=0.20.3 && <0.21,+    servant-client-core,+    servant-openapi-hs,+    servant-server,+    sop-core >=0.5 && <0.6,+    tasty >=1.4 && <1.6,+    tasty-hunit >=0.10 && <0.11,+    text,+    wai,+    warp >=3.3 && <3.5,  executable relay-demo-  import:         lang+  import: lang   hs-source-dirs: demo-  main-is:        Main.hs-  other-modules:  ToyApi-+  main-is: Main.hs+  other-modules: ToyApi   -- warp requires the threaded RTS (its TimerManager will not start without it)-  ghc-options:    -threaded+  ghc-options: -threaded   build-depends:-    , aeson-    , base-    , openapi-hs-    , relay-pagination          ^>=0.1.1.2-    , relay-pagination-servant-    , servant-    , servant-server-    , sop-core                  >=0.5      && <0.6-    , text-    , wai-    , warp                      >=3.3      && <3.5+    aeson,+    base,+    openapi-hs,+    relay-pagination ^>=0.2.0.0,+    relay-pagination-servant,+    servant,+    servant-server,+    sop-core >=0.5 && <0.6,+    text,+    wai,+    warp >=3.3 && <3.5,  executable relay-demo-openapi-  import:         lang+  import: lang   hs-source-dirs: demo-  main-is:        OpenApiMain.hs+  main-is: OpenApiMain.hs   other-modules:+    CountedToyApi     ToyApi     ToyOpenApi    build-depends:-    , aeson-    , aeson-pretty              >=0.8      && <0.9-    , base-    , bytestring                >=0.11     && <0.13-    , lens-    , openapi-hs-    , relay-pagination          ^>=0.1.1.2-    , relay-pagination-servant-    , servant-    , servant-openapi-hs-    , servant-server-    , sop-core                  >=0.5      && <0.6-    , text-    , wai+    aeson,+    aeson-pretty >=0.8 && <0.9,+    base,+    bytestring >=0.11 && <0.13,+    lens,+    openapi-hs,+    relay-pagination ^>=0.2.0.0,+    relay-pagination-servant,+    servant,+    servant-openapi-hs,+    servant-server,+    sop-core >=0.5 && <0.6,+    text,+    wai,
src/Relay/Pagination/Servant/OpenApi.hs view
@@ -5,7 +5,8 @@ -- -- This module is the __canonical (sole permitted) home__ of the OpenAPI -- orphan instances for the core @relay-pagination@ types ('Cursor',--- 'PageInfo', 'Edge', 'Connection') and for 'RelayPageError'. The core+-- 'PageInfo', 'Edge', 'Connection', 'CountedConnection') and for+-- 'RelayPageError'. The core -- package must not depend on @openapi-hs@, and @openapi-hs@ cannot know -- about this library, so orphans are the standard escape hatch — the danger -- of orphans is duplicate definitions elsewhere, therefore no other package@@ -20,7 +21,7 @@ -- an error the route type omitted. module Relay.Pagination.Servant.OpenApi () where -import Control.Lens ((&), (.~), (?~))+import Control.Lens (at, (%~), (&), (.~), (?~)) import Data.Aeson (toJSON) import Data.OpenApi import Data.Proxy (Proxy (..))@@ -121,4 +122,14 @@   declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions  instance (ToSchema a) => ToSchema (Connection a) where-  declareNamedSchema = genericDeclareNamedSchema defaultSchemaOptions+  declareNamedSchema proxy = do+    NamedSchema connectionName connectionSchema <- genericDeclareNamedSchema defaultSchemaOptions proxy+    pure $ NamedSchema connectionName (connectionSchema & properties . at "totalCount" .~ Nothing)++instance (ToSchema a) => ToSchema (CountedConnection a) where+  declareNamedSchema _ = do+    NamedSchema connectionName connectionSchema <- genericDeclareNamedSchema defaultSchemaOptions (Proxy @(Connection a))+    pure $+      NamedSchema+        (("Counted" <>) <$> connectionName)+        (connectionSchema & required %~ (<> ["totalCount"]))
test/Main.hs view
@@ -3,6 +3,7 @@ module Main (main) where  import Control.Lens ((^.), (^..))+import CountedToyApi import Data.Aeson qualified as Aeson import Data.Aeson.KeyMap qualified as KeyMap import Data.ByteString.Lazy (ByteString)@@ -15,6 +16,7 @@ import Data.Text qualified as Text import Network.HTTP.Client qualified as HttpClient import Network.HTTP.Types (statusCode)+import Network.Wai (Application) import Network.Wai.Handler.Warp (testWithApplication) import Relay.Pagination import Relay.Pagination.Servant@@ -25,7 +27,7 @@ import Test.Tasty import Test.Tasty.HUnit import ToyApi-import ToyOpenApi (renderToyOpenApi, toyOpenApi)+import ToyOpenApi (countedToyOpenApi, renderCountedToyOpenApi, renderToyOpenApi, toyOpenApi) import Web.HttpApiData (toUrlPiece)  main :: IO ()@@ -33,7 +35,7 @@   defaultMain $     testGroup       "relay-pagination-servant"-      [serverTests, clientTests, linkTests, openapiTests]+      [serverTests, clientTests, linkTests, openapiTests, countedTests]  -- * The RelayPage HasServer instance, over real HTTP (M2) @@ -105,7 +107,8 @@                         hasPreviousPage = False,                         startCursor = Just toyCursor,                         endCursor = Just toyCursor-                      }+                      },+                  totalCount = Nothing                 }           other -> assertFailure ("expected ToyPageOk, got " <> show other),       withToyClient "typed backward round trip" (backwardPage 3 (Just toyCursor)) \result ->@@ -219,7 +222,8 @@                 hasPreviousPage = False,                 startCursor = Just toyCursor,                 endCursor = Just toyCursor-              }+              },+          totalCount = Nothing         }      exampleError :: RelayPageError@@ -231,14 +235,67 @@           parameter = Just "last"         } +-- * Counted connections++countedTests :: TestTree+countedTests =+  testGroup+    "counted connections"+    [ testCase "counted artifact matches generator" $ do+        checked <- LBS.readFile "test/golden/toy-counted-openapi.json"+        checked @?= renderCountedToyOpenApi,+      testCase "counted schema requires a non-negative integer totalCount" $+        case InsOrd.lookup "CountedConnection_Item" countedSchemas of+          Nothing -> assertFailure "missing CountedConnection_Item schema"+          Just s -> do+            assertBool "totalCount is required" ("totalCount" `elem` (s ^. OpenApi.required))+            case InsOrd.lookup "totalCount" (s ^. OpenApi.properties) of+              Just (OpenApi.Inline count) -> do+                count ^. OpenApi.type_ @?= Just (OpenApi.OpenApiTypeSingle OpenApi.OpenApiInteger)+                count ^. OpenApi.minimum_ @?= Just 0+              other -> assertFailure ("expected an inline totalCount schema, got " <> show other),+      testCase "uncounted path and schema match the original document" $ do+        let originalSchemas = toyOpenApi ^. OpenApi.components . OpenApi.schemas+        case InsOrd.lookup "Connection_Item" countedSchemas of+          Nothing -> assertFailure "missing Connection_Item schema"+          Just s -> do+            Just s @?= InsOrd.lookup "Connection_Item" originalSchemas+            InsOrd.lookup "totalCount" (s ^. OpenApi.properties) @?= Nothing+        let itemsPath doc = InsOrd.lookup "/items" (doc ^. OpenApi.paths)+        itemsPath countedToyOpenApi @?= itemsPath toyOpenApi,+      testCase "counted JSON validates against its schema" $+        OpenApi.validateToJSON (countedConnection 42 (echoPage request)) @?= [],+      withApp countedToyApp "counted route returns totalCount over raw HTTP" "/counted-items?first=7" \(status, body) -> do+        status @?= 200+        raw <- decodeOk @Aeson.Object body+        KeyMap.lookup "totalCount" raw @?= Just (Aeson.Number 42)+        decodeOk @(CountedConnection Item) body >>= (@?= countedConnection 42 (echoPage request)),+      testCase "typed client decodes a counted connection" $+        testWithApplication (pure countedToyApp) \port -> do+          manager <- HttpClient.newManager HttpClient.defaultManagerSettings+          let env = mkClientEnv manager (BaseUrl Http "127.0.0.1" port "")+          result <- runClientM (countedItems countedClient (forwardPage 7 Nothing)) env+          case result of+            Right (CountedToyOk conn) -> conn @?= countedConnection 42 (echoPage request)+            other -> assertFailure ("expected CountedToyOk, got " <> show other)+    ]+  where+    request = PageRequest {pageSize = 7, direction = Forward, cursor = Nothing}+    countedSchemas = countedToyOpenApi ^. OpenApi.components . OpenApi.schemas+    countedClient :: CountedToyRoutes (AsClientT ClientM)+    countedClient = genericClient+ -- * Helpers  -- | Run the toy app on a free port and hit it with one raw HTTP request, so -- malformed query strings reach the combinator verbatim. withToy :: TestName -> Text -> ((Int, ByteString) -> Assertion) -> TestTree-withToy name pathAndQuery check =+withToy = withApp toyApp++withApp :: Application -> TestName -> Text -> ((Int, ByteString) -> Assertion) -> TestTree+withApp app name pathAndQuery check =   testCase name $-    testWithApplication (pure toyApp) \port -> do+    testWithApplication (pure app) \port -> do       manager <- HttpClient.newManager HttpClient.defaultManagerSettings       request <-         HttpClient.parseRequest
+ test/golden/toy-counted-openapi.json view
@@ -0,0 +1,298 @@+{+    "components": {+        "schemas": {+            "Connection_Item": {+                "properties": {+                    "edges": {+                        "items": {+                            "$ref": "#/components/schemas/Edge_Item"+                        },+                        "type": "array"+                    },+                    "pageInfo": {+                        "$ref": "#/components/schemas/PageInfo"+                    }+                },+                "required": [+                    "edges",+                    "pageInfo"+                ],+                "type": "object"+            },+            "CountedConnection_Item": {+                "properties": {+                    "edges": {+                        "items": {+                            "$ref": "#/components/schemas/Edge_Item"+                        },+                        "type": "array"+                    },+                    "pageInfo": {+                        "$ref": "#/components/schemas/PageInfo"+                    },+                    "totalCount": {+                        "minimum": 0,+                        "type": "integer"+                    }+                },+                "required": [+                    "edges",+                    "pageInfo",+                    "totalCount"+                ],+                "type": "object"+            },+            "Cursor": {+                "description": "opaque pagination cursor",+                "format": "base64url",+                "type": "string"+            },+            "Edge_Item": {+                "properties": {+                    "cursor": {+                        "$ref": "#/components/schemas/Cursor"+                    },+                    "node": {+                        "$ref": "#/components/schemas/Item"+                    }+                },+                "required": [+                    "node",+                    "cursor"+                ],+                "type": "object"+            },+            "Item": {+                "properties": {+                    "itemId": {+                        "maximum": 9223372036854775807,+                        "minimum": -9223372036854775808,+                        "type": "integer"+                    },+                    "itemName": {+                        "type": "string"+                    }+                },+                "required": [+                    "itemId",+                    "itemName"+                ],+                "type": "object"+            },+            "PageInfo": {+                "properties": {+                    "endCursor": {+                        "$ref": "#/components/schemas/Cursor"+                    },+                    "hasNextPage": {+                        "type": "boolean"+                    },+                    "hasPreviousPage": {+                        "type": "boolean"+                    },+                    "startCursor": {+                        "$ref": "#/components/schemas/Cursor"+                    }+                },+                "required": [+                    "hasNextPage",+                    "hasPreviousPage"+                ],+                "type": "object"+            },+            "RelayPageError": {+                "properties": {+                    "code": {+                        "type": "string"+                    },+                    "message": {+                        "type": "string"+                    },+                    "parameter": {+                        "type": "string"+                    },+                    "retryable": {+                        "type": "boolean"+                    }+                },+                "required": [+                    "code",+                    "message",+                    "retryable"+                ],+                "type": "object"+            }+        }+    },+    "info": {+        "title": "",+        "version": ""+    },+    "openapi": "3.1.0",+    "paths": {+        "/counted-items": {+            "get": {+                "operationId": "getCountedItems",+                "parameters": [+                    {+                        "description": "Forward page size (0..100). Defaults to 10 when neither 'first' nor 'last' is given. Cannot be combined with 'last' or 'before'.",+                        "in": "query",+                        "name": "first",+                        "required": false,+                        "schema": {+                            "default": 10,+                            "maximum": 100,+                            "minimum": 0,+                            "type": "integer"+                        }+                    },+                    {+                        "description": "Opaque cursor: return items after this position (forward pagination).",+                        "in": "query",+                        "name": "after",+                        "required": false,+                        "schema": {+                            "format": "base64url",+                            "type": "string"+                        }+                    },+                    {+                        "description": "Backward page size (0..100). Cannot be combined with 'first' or 'after'.",+                        "in": "query",+                        "name": "last",+                        "required": false,+                        "schema": {+                            "maximum": 100,+                            "minimum": 0,+                            "type": "integer"+                        }+                    },+                    {+                        "description": "Opaque cursor: return items before this position (backward pagination).",+                        "in": "query",+                        "name": "before",+                        "required": false,+                        "schema": {+                            "format": "base64url",+                            "type": "string"+                        }+                    }+                ],+                "responses": {+                    "200": {+                        "content": {+                            "application/json": {+                                "schema": {+                                    "$ref": "#/components/schemas/CountedConnection_Item"+                                }+                            },+                            "application/json;charset=utf-8": {+                                "schema": {+                                    "$ref": "#/components/schemas/CountedConnection_Item"+                                }+                            }+                        },+                        "description": "Counted page of items"+                    },+                    "400": {+                        "content": {+                            "application/json": {+                                "schema": {+                                    "$ref": "#/components/schemas/RelayPageError"+                                }+                            },+                            "application/json;charset=utf-8": {+                                "schema": {+                                    "$ref": "#/components/schemas/RelayPageError"+                                }+                            }+                        },+                        "description": "Invalid pagination"+                    }+                }+            }+        },+        "/items": {+            "get": {+                "operationId": "getItems",+                "parameters": [+                    {+                        "description": "Forward page size (0..100). Defaults to 10 when neither 'first' nor 'last' is given. Cannot be combined with 'last' or 'before'.",+                        "in": "query",+                        "name": "first",+                        "required": false,+                        "schema": {+                            "default": 10,+                            "maximum": 100,+                            "minimum": 0,+                            "type": "integer"+                        }+                    },+                    {+                        "description": "Opaque cursor: return items after this position (forward pagination).",+                        "in": "query",+                        "name": "after",+                        "required": false,+                        "schema": {+                            "format": "base64url",+                            "type": "string"+                        }+                    },+                    {+                        "description": "Backward page size (0..100). Cannot be combined with 'first' or 'after'.",+                        "in": "query",+                        "name": "last",+                        "required": false,+                        "schema": {+                            "maximum": 100,+                            "minimum": 0,+                            "type": "integer"+                        }+                    },+                    {+                        "description": "Opaque cursor: return items before this position (backward pagination).",+                        "in": "query",+                        "name": "before",+                        "required": false,+                        "schema": {+                            "format": "base64url",+                            "type": "string"+                        }+                    }+                ],+                "responses": {+                    "200": {+                        "content": {+                            "application/json": {+                                "schema": {+                                    "$ref": "#/components/schemas/Connection_Item"+                                }+                            },+                            "application/json;charset=utf-8": {+                                "schema": {+                                    "$ref": "#/components/schemas/Connection_Item"+                                }+                            }+                        },+                        "description": "Page of items"+                    },+                    "400": {+                        "content": {+                            "application/json": {+                                "schema": {+                                    "$ref": "#/components/schemas/RelayPageError"+                                }+                            },+                            "application/json;charset=utf-8": {+                                "schema": {+                                    "$ref": "#/components/schemas/RelayPageError"+                                }+                            }+                        },+                        "description": "Invalid pagination"+                    }+                }+            }+        }+    }+}
+ test/golden/toy-openapi.json view
@@ -0,0 +1,193 @@+{+    "components": {+        "schemas": {+            "Connection_Item": {+                "properties": {+                    "edges": {+                        "items": {+                            "$ref": "#/components/schemas/Edge_Item"+                        },+                        "type": "array"+                    },+                    "pageInfo": {+                        "$ref": "#/components/schemas/PageInfo"+                    }+                },+                "required": [+                    "edges",+                    "pageInfo"+                ],+                "type": "object"+            },+            "Cursor": {+                "description": "opaque pagination cursor",+                "format": "base64url",+                "type": "string"+            },+            "Edge_Item": {+                "properties": {+                    "cursor": {+                        "$ref": "#/components/schemas/Cursor"+                    },+                    "node": {+                        "$ref": "#/components/schemas/Item"+                    }+                },+                "required": [+                    "node",+                    "cursor"+                ],+                "type": "object"+            },+            "Item": {+                "properties": {+                    "itemId": {+                        "maximum": 9223372036854775807,+                        "minimum": -9223372036854775808,+                        "type": "integer"+                    },+                    "itemName": {+                        "type": "string"+                    }+                },+                "required": [+                    "itemId",+                    "itemName"+                ],+                "type": "object"+            },+            "PageInfo": {+                "properties": {+                    "endCursor": {+                        "$ref": "#/components/schemas/Cursor"+                    },+                    "hasNextPage": {+                        "type": "boolean"+                    },+                    "hasPreviousPage": {+                        "type": "boolean"+                    },+                    "startCursor": {+                        "$ref": "#/components/schemas/Cursor"+                    }+                },+                "required": [+                    "hasNextPage",+                    "hasPreviousPage"+                ],+                "type": "object"+            },+            "RelayPageError": {+                "properties": {+                    "code": {+                        "type": "string"+                    },+                    "message": {+                        "type": "string"+                    },+                    "parameter": {+                        "type": "string"+                    },+                    "retryable": {+                        "type": "boolean"+                    }+                },+                "required": [+                    "code",+                    "message",+                    "retryable"+                ],+                "type": "object"+            }+        }+    },+    "info": {+        "title": "",+        "version": ""+    },+    "openapi": "3.1.0",+    "paths": {+        "/items": {+            "get": {+                "operationId": "getItems",+                "parameters": [+                    {+                        "description": "Forward page size (0..100). Defaults to 10 when neither 'first' nor 'last' is given. Cannot be combined with 'last' or 'before'.",+                        "in": "query",+                        "name": "first",+                        "required": false,+                        "schema": {+                            "default": 10,+                            "maximum": 100,+                            "minimum": 0,+                            "type": "integer"+                        }+                    },+                    {+                        "description": "Opaque cursor: return items after this position (forward pagination).",+                        "in": "query",+                        "name": "after",+                        "required": false,+                        "schema": {+                            "format": "base64url",+                            "type": "string"+                        }+                    },+                    {+                        "description": "Backward page size (0..100). Cannot be combined with 'first' or 'after'.",+                        "in": "query",+                        "name": "last",+                        "required": false,+                        "schema": {+                            "maximum": 100,+                            "minimum": 0,+                            "type": "integer"+                        }+                    },+                    {+                        "description": "Opaque cursor: return items before this position (backward pagination).",+                        "in": "query",+                        "name": "before",+                        "required": false,+                        "schema": {+                            "format": "base64url",+                            "type": "string"+                        }+                    }+                ],+                "responses": {+                    "200": {+                        "content": {+                            "application/json": {+                                "schema": {+                                    "$ref": "#/components/schemas/Connection_Item"+                                }+                            },+                            "application/json;charset=utf-8": {+                                "schema": {+                                    "$ref": "#/components/schemas/Connection_Item"+                                }+                            }+                        },+                        "description": "Page of items"+                    },+                    "400": {+                        "content": {+                            "application/json": {+                                "schema": {+                                    "$ref": "#/components/schemas/RelayPageError"+                                }+                            },+                            "application/json;charset=utf-8": {+                                "schema": {+                                    "$ref": "#/components/schemas/RelayPageError"+                                }+                            }+                        },+                        "description": "Invalid pagination"+                    }+                }+            }+        }+    }+}