diff --git a/.changesets/1793711888-00a6fda2.yaml b/.changesets/1793711888-00a6fda2.yaml new file mode 100644 index 000000000..3a3592114 --- /dev/null +++ b/.changesets/1793711888-00a6fda2.yaml @@ -0,0 +1,13 @@ +id: 1793711888-00a6fda2 +features: + - pagination +targets: + - csharp + - unity + - php + - ruby +type: fix +bump: patch +description: keep paginating on the result length when a response omits or nulls numPages +author: AshGodfrey +date: "2026-11-03" diff --git a/internal/features/tests.go b/internal/features/tests.go index ab7ccd96b..9a67ada02 100644 --- a/internal/features/tests.go +++ b/internal/features/tests.go @@ -403,6 +403,7 @@ const ( TestPaginationLimitOffsetPageBody TestPaginationLimitOffsetPageBodyNullable TestPaginationLimitOffsetPageBodyOptionalNullable + TestPaginationLimitOffsetPageNumPagesMissing TestPaginationLimitOffsetDeepOutputsPageBody TestPaginationLimitOffsetPageParams TestPaginationLimitOffsetPageParamsFlat diff --git a/internal/features/tests_generated.go b/internal/features/tests_generated.go index f38dc5beb..530f9d9b6 100644 --- a/internal/features/tests_generated.go +++ b/internal/features/tests_generated.go @@ -672,6 +672,8 @@ func (t Test) String() string { return "pagination-limit-offset-page-body-nullable" case TestPaginationLimitOffsetPageBodyOptionalNullable: return "pagination-limit-offset-page-body-optional-nullable" + case TestPaginationLimitOffsetPageNumPagesMissing: + return "pagination-limit-offset-page-num-pages-missing" case TestPaginationLimitOffsetPageParams: return "pagination-limit-offset-page-params" case TestPaginationLimitOffsetPageParamsConst: @@ -2228,6 +2230,8 @@ func TestFromString(s string) Test { return TestPaginationLimitOffsetPageBodyNullable case "pagination-limit-offset-page-body-optional-nullable": return TestPaginationLimitOffsetPageBodyOptionalNullable + case "pagination-limit-offset-page-num-pages-missing": + return TestPaginationLimitOffsetPageNumPagesMissing case "pagination-limit-offset-page-params": return TestPaginationLimitOffsetPageParams case "pagination-limit-offset-page-params-const": @@ -3449,6 +3453,7 @@ var testList = []Test{ TestPaginationLimitOffsetPageBody, TestPaginationLimitOffsetPageBodyNullable, TestPaginationLimitOffsetPageBodyOptionalNullable, + TestPaginationLimitOffsetPageNumPagesMissing, TestPaginationLimitOffsetPageParams, TestPaginationLimitOffsetPageParamsConst, TestPaginationLimitOffsetPageParamsFlat, diff --git a/services/speakeasy-api-test-service/cmd/server/main.go b/services/speakeasy-api-test-service/cmd/server/main.go index 0b2fcac21..0a7ccbfa1 100644 --- a/services/speakeasy-api-test-service/cmd/server/main.go +++ b/services/speakeasy-api-test-service/cmd/server/main.go @@ -67,6 +67,7 @@ func main() { r.HandleFunc("/pagination/cursor/deep_nested_outputs", pagination.HandleCursorDeepNestedOutputs).Methods(http.MethodGet) r.HandleFunc("/pagination/limitoffset/nullable_offset", pagination.HandleLimitOffsetNullable).Methods(http.MethodGet) r.HandleFunc("/pagination/limitoffset/nullable_body", pagination.HandleLimitOffsetPageNullableBody).Methods(http.MethodPut) + r.HandleFunc("/pagination/limitoffset/page/num_pages_missing", pagination.HandleLimitOffsetPageNumPagesMissing).Methods(http.MethodGet) r.HandleFunc("/retries", retries.HandleRetries).Methods(http.MethodGet, http.MethodPost) r.HandleFunc("/errors/errorUnion/malformed", errors.HandleMalformedErrorUnionResponse).Methods(http.MethodGet) r.HandleFunc("/errors/{status_code}", errors.HandleErrors).Methods(http.MethodGet, http.MethodPost) diff --git a/services/speakeasy-api-test-service/internal/pagination/service.go b/services/speakeasy-api-test-service/internal/pagination/service.go index 2d953d9a9..bb53a7a3d 100644 --- a/services/speakeasy-api-test-service/internal/pagination/service.go +++ b/services/speakeasy-api-test-service/internal/pagination/service.go @@ -545,3 +545,41 @@ func getNonNumericValue(queryValue string, hasBody bool, paginationValue string) } } } + +// HandleLimitOffsetPageNumPagesMissing serves three pages of seven items where +// the first response omits numPages and the second carries numPages: null, so +// only the final page states the total. Pagination must advance through the +// first two pages on the result length and stop after the third. +func HandleLimitOffsetPageNumPagesMissing(w http.ResponseWriter, r *http.Request) { + const limit = 7 + + page, err := strconv.Atoi(r.FormValue("page")) + if err != nil || page < 1 { + page = 1 + } + if requested := r.FormValue("limit"); requested != "" && requested != strconv.Itoa(limit) { + w.WriteHeader(http.StatusBadRequest) + _, _ = w.Write([]byte("limit must be 7")) + return + } + + start := (page - 1) * limit + results := make([]interface{}, 0) + for i := start; i < total && len(results) < limit; i++ { + results = append(results, i) + } + + res := map[string]interface{}{"resultArray": results} + switch page { + case 1: + case 2: + res["numPages"] = nil + default: + res["numPages"] = int(math.Ceil(float64(total) / float64(limit))) + } + + w.Header().Set("Content-Type", "application/json") + if err := json.NewEncoder(w).Encode(res); err != nil { + w.WriteHeader(500) + } +} diff --git a/templates/templates/cli/features.ts b/templates/templates/cli/features.ts index 17da1d0b5..e3c687e27 100644 --- a/templates/templates/cli/features.ts +++ b/templates/templates/cli/features.ts @@ -373,6 +373,7 @@ function isTestSkipped(test: string): boolean { "unions-body-variant-overloads-nested-union", "unions-body-variant-overloads-open-enum", "request-bodies-base64-file-input-raw-bytes", + "pagination-limit-offset-page-num-pages-missing", ].includes(test); } diff --git a/templates/templates/csharp/pagination.cs.stmpl b/templates/templates/csharp/pagination.cs.stmpl index 32bb9532b..415641f2d 100644 --- a/templates/templates/csharp/pagination.cs.stmpl +++ b/templates/templates/csharp/pagination.cs.stmpl @@ -18,10 +18,17 @@ Func> nextFunc = async d var numPages = body.SelectToken("{{ sanitizeJsonPath $pagination.Outputs.NumPages }}"); + {{- if $pagination.Outputs.Results }} + if (numPages != null && (numPages.Type == JTokenType.Integer || numPages.Type == JTokenType.Float) && numPages.Value() <= page) + { + return null; + } + {{- else }} if (numPages == null || numPages.Value() <= page) { return null; } + {{- end }} {{- end }} {{- end }} diff --git a/templates/templates/csharp/tests/primary/PaginationShould.cs b/templates/templates/csharp/tests/primary/PaginationShould.cs index ae24d7e57..19106c287 100644 --- a/templates/templates/csharp/tests/primary/PaginationShould.cs +++ b/templates/templates/csharp/tests/primary/PaginationShould.cs @@ -207,6 +207,39 @@ public async Task PaginationLimitOffsetPageBodyNullable() Assert.Null(nullRes); } + [Fact] + public async Task PaginationLimitOffsetPageNumPagesMissing() + { + CommonHelpers.RecordTest("pagination-limit-offset-page-num-pages-missing"); + var sdk = new SDK(serverUrl: Helpers.HttpBinUrl); + + // the test service omits numPages on the first page and returns null on + // the second, so termination must fall back to the result length + var res = await sdk.Pagination.PaginationLimitOffsetPageNumPagesMissingAsync(page: 1, limit: 7); + + Assert.Equal(HttpStatusCode.OK, res.HttpMeta.Response.StatusCode); + Assert.NotNull(res.Res); + Assert.False(res.Res.NumPages.IsSet); + Assert.Equal(new List { 0, 1, 2, 3, 4, 5, 6 }, res.Res.ResultArray); + + var nextRes = await res.Next!(); + Assert.NotNull(nextRes); + Assert.Equal(HttpStatusCode.OK, nextRes.HttpMeta.Response.StatusCode); + Assert.NotNull(nextRes.Res); + Assert.True(nextRes.Res.NumPages.IsNull); + Assert.Equal(new List { 7, 8, 9, 10, 11, 12, 13 }, nextRes.Res.ResultArray); + + var lastRes = await nextRes.Next!(); + Assert.NotNull(lastRes); + Assert.Equal(HttpStatusCode.OK, lastRes.HttpMeta.Response.StatusCode); + Assert.NotNull(lastRes.Res); + Assert.Equal(3L, lastRes.Res.NumPages.Value); + Assert.Equal(new List { 14, 15, 16, 17, 18, 19 }, lastRes.Res.ResultArray); + + var nullRes = await lastRes.Next!(); + Assert.Null(nullRes); + } + [Fact] public async Task PaginationLimitOffsetDeepOutputsPageBody() { diff --git a/templates/templates/go/features.ts b/templates/templates/go/features.ts index f5cc4f03d..93756e1d5 100644 --- a/templates/templates/go/features.ts +++ b/templates/templates/go/features.ts @@ -442,6 +442,7 @@ function isTestSkipped(test: string): boolean { "unions-body-variant-overloads-nested-union", "unions-body-variant-overloads-open-enum", "request-bodies-base64-file-input-raw-bytes", + "pagination-limit-offset-page-num-pages-missing", ].includes(test); } diff --git a/templates/templates/javav2/tests/primary/PaginationAdditionalTest.java b/templates/templates/javav2/tests/primary/PaginationAdditionalTest.java index 5e6d400ad..f38c85f60 100644 --- a/templates/templates/javav2/tests/primary/PaginationAdditionalTest.java +++ b/templates/templates/javav2/tests/primary/PaginationAdditionalTest.java @@ -40,6 +40,7 @@ import org.openapis.openapi.models.operations.PaginationLimitOffsetOptionalPageParamsResponse; import org.openapis.openapi.models.operations.PaginationLimitOffsetPageBodyNullableResponse; import org.openapis.openapi.models.operations.PaginationLimitOffsetPageBodyResponse; +import org.openapis.openapi.models.operations.PaginationLimitOffsetPageNumPagesMissingResponse; import org.openapis.openapi.models.operations.PaginationOffsetNullableResponse; import org.openapis.openapi.models.operations.PaginationLimitOffsetPageParamsResponse; import org.openapis.openapi.models.operations.PaginationURLParamsResponse; @@ -154,6 +155,45 @@ void paginationLimitOffsetPageBodyNullable() throws Exception { pages); } + @Test + void paginationLimitOffsetPageNumPagesMissing() throws Exception { + recordTest("pagination-limit-offset-page-num-pages-missing"); + + SDK s = SDK.builder().serverURL(Helpers.HTTPBIN_URL).build(); + + // the test service omits numPages on the first page and returns null on + // the second, so termination must fall back to the result length + Iterator iterator = s.pagination() + .paginationLimitOffsetPageNumPagesMissing() + .page(1) + .limit(7L) + .callAsIterable().iterator(); + + assertTrue(iterator.hasNext()); + PaginationLimitOffsetPageNumPagesMissingResponse res = iterator.next(); + assertEquals(200, res.statusCode()); + assertTrue(res.res().isPresent()); + assertFalse(res.res().get().numPages().isPresent()); + assertEquals(List.of(0L, 1L, 2L, 3L, 4L, 5L, 6L), res.res().get().resultArray()); + + assertTrue(iterator.hasNext()); + PaginationLimitOffsetPageNumPagesMissingResponse nextRes = iterator.next(); + assertEquals(200, nextRes.statusCode()); + assertTrue(nextRes.res().isPresent()); + assertTrue(nextRes.res().get().numPages().isPresent()); + assertNull(nextRes.res().get().numPages().get()); + assertEquals(List.of(7L, 8L, 9L, 10L, 11L, 12L, 13L), nextRes.res().get().resultArray()); + + assertTrue(iterator.hasNext()); + PaginationLimitOffsetPageNumPagesMissingResponse lastRes = iterator.next(); + assertEquals(200, lastRes.statusCode()); + assertTrue(lastRes.res().isPresent()); + assertEquals(3L, lastRes.res().get().numPages().get()); + assertEquals(List.of(14L, 15L, 16L, 17L, 18L, 19L), lastRes.res().get().resultArray()); + + assertFalse(iterator.hasNext()); + } + @Test void paginationWrappedOptionalBody() throws Exception { recordTest("pagination-wrapped-optional-body"); diff --git a/templates/templates/mcp-typescript/features.ts b/templates/templates/mcp-typescript/features.ts index 32c4084c7..29556e6ea 100644 --- a/templates/templates/mcp-typescript/features.ts +++ b/templates/templates/mcp-typescript/features.ts @@ -704,6 +704,7 @@ function isTestSkipped(test: string): boolean { "unions-body-variant-overloads-nested-union", "unions-body-variant-overloads-open-enum", "request-bodies-base64-file-input-raw-bytes", + "pagination-limit-offset-page-num-pages-missing", ].includes(test); } diff --git a/templates/templates/php/Tests/primary/PaginationTest.php b/templates/templates/php/Tests/primary/PaginationTest.php index c11c02560..b13fb165d 100644 --- a/templates/templates/php/Tests/primary/PaginationTest.php +++ b/templates/templates/php/Tests/primary/PaginationTest.php @@ -140,6 +140,39 @@ public function testPaginationLimitOffsetPageBodyNullable(): void ], $pages); } + public function testPaginationLimitOffsetPageNumPagesMissing(): void + { + CommonHelpers::recordTest('pagination-limit-offset-page-num-pages-missing'); + + $sdk = \OpenAPI\OpenAPI\SDK::builder()->setServerUrl(Helpers::getHttpBinUrl())->build(); + + $this->assertInstanceOf(\OpenAPI\OpenAPI\SDK::class, $sdk); + + // the test service omits numPages on the first page and returns null on + // the second, so termination must fall back to the result length + $responses = $sdk->pagination->paginationLimitOffsetPageNumPagesMissing(page: 1, limit: 7); + + $pages = []; + $numPages = []; + $last = null; + foreach ($responses as $response) { + $this->assertEquals(200, $response->httpMeta->response->getStatusCode()); + $this->assertNotNull($response->res); + $pages[] = $response->res->resultArray; + $numPages[] = $response->res->numPages; + $last = $response; + } + + $this->assertEquals([ + [0, 1, 2, 3, 4, 5, 6], + [7, 8, 9, 10, 11, 12, 13], + [14, 15, 16, 17, 18, 19], + ], $pages); + $this->assertSame([null, null, 3], $numPages); + $this->assertNotNull($last); + $this->assertNull(($last->next)()); + } + public function testPaginationLimitOffsetDeepOutputsPageBody(): void { CommonHelpers::recordTest('pagination-limit-offset-deep-outputs-page-body'); diff --git a/templates/templates/php/includes/responses.ts b/templates/templates/php/includes/responses.ts index ec11dcf60..addf39a2b 100644 --- a/templates/templates/php/includes/responses.ts +++ b/templates/templates/php/includes/responses.ts @@ -292,9 +292,15 @@ function templatePagination(op: Operation): string { op.Extensions.Pagination.Outputs.NumPages, )}');\n`; } - response += `${indent}if ($numPages == null || $numPages[0] <= $page) { + if (op.Extensions.Pagination.Outputs.Results) { + response += `${indent}if (is_array($numPages) && isset($numPages[0]) && is_numeric($numPages[0]) && $numPages[0] <= $page) { return null; }\n`; + } else { + response += `${indent}if ($numPages == null || $numPages[0] <= $page) { + return null; + }\n`; + } } } diff --git a/templates/templates/pythonv2/features.ts b/templates/templates/pythonv2/features.ts index 4b08ad4ad..b28650d5f 100644 --- a/templates/templates/pythonv2/features.ts +++ b/templates/templates/pythonv2/features.ts @@ -446,6 +446,7 @@ function isTestSkipped(test: string): boolean { "unions-body-variant-overloads-request-body", "unions-body-variant-overloads-nested-union", "unions-body-variant-overloads-open-enum", + "pagination-limit-offset-page-num-pages-missing", ].includes(test); } diff --git a/templates/templates/ruby/includes/responses.ts b/templates/templates/ruby/includes/responses.ts index 6495f3a5a..536040318 100644 --- a/templates/templates/ruby/includes/responses.ts +++ b/templates/templates/ruby/includes/responses.ts @@ -411,9 +411,15 @@ function templatePagination(op: Operation): string { op.Extensions.Pagination.Outputs.NumPages, )}', ::JSON.parse(response_data)).search\n`; } - response += `${indent}if num_pages.nil? || num_pages[0] <= request_page + if (op.Extensions.Pagination.Outputs.Results) { + response += `${indent}if !num_pages.nil? && num_pages[0].is_a?(Numeric) && num_pages[0] <= request_page next nil end\n`; + } else { + response += `${indent}if num_pages.nil? || num_pages[0] <= request_page + next nil + end\n`; + } } } diff --git a/templates/templates/ruby/tests/primary/pagination_additional_test.rb b/templates/templates/ruby/tests/primary/pagination_additional_test.rb index e6515c7a5..3ffba25e7 100644 --- a/templates/templates/ruby/tests/primary/pagination_additional_test.rb +++ b/templates/templates/ruby/tests/primary/pagination_additional_test.rb @@ -164,6 +164,39 @@ def test_pagination_limit_offset_page_body_nullable ) end + def test_pagination_limit_offset_page_num_pages_missing + record_test("pagination-limit-offset-page-num-pages-missing") + + assert_instance_of(OpenApiSDK::SDK, @sdk) + + # the test service omits numPages on the first page and returns null on + # the second, so termination must fall back to the result length + responses = @sdk + .pagination + .pagination_limit_offset_page_num_pages_missing(page: 1, limit: 7) + + pages = [] + num_pages = [] + last = nil + responses.each do |response| + assert(response) + assert(response.http_meta) + assert(response.http_meta.response) + assert_equal(200, response.http_meta.response.status) + assert(response.res) + pages << response.res.result_array + num_pages << response.res.num_pages + last = response + end + + assert_equal( + [[0, 1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12, 13], [14, 15, 16, 17, 18, 19]], + pages + ) + assert_equal([nil, nil, 3], num_pages) + assert_nil(T.must(last).next_page.call) + end + def test_pagination_limit_offset_deep_outputs_page_body record_test("pagination-limit-offset-deep-outputs-page-body") diff --git a/templates/templates/typescriptv2/features.ts b/templates/templates/typescriptv2/features.ts index ae452ee9d..88a926671 100644 --- a/templates/templates/typescriptv2/features.ts +++ b/templates/templates/typescriptv2/features.ts @@ -439,6 +439,7 @@ function isTestSkipped(test: string): boolean { "unions-body-variant-overloads-nested-union", "unions-body-variant-overloads-open-enum", "request-bodies-base64-file-input-raw-bytes", + "pagination-limit-offset-page-num-pages-missing", ].includes(test); } diff --git a/templates/templates/unity/pagination.cs.stmpl b/templates/templates/unity/pagination.cs.stmpl index 04df12cc4..d558c744a 100644 --- a/templates/templates/unity/pagination.cs.stmpl +++ b/templates/templates/unity/pagination.cs.stmpl @@ -23,10 +23,17 @@ var numPages = body.SelectToken("{{ sanitizeJsonPath $pagination.Outputs.NumPages }}"); + {{- if $pagination.Outputs.Results }} + if (numPages != null && (numPages.Type == JTokenType.Integer || numPages.Type == JTokenType.Float) && numPages.Value() <= page) + { + return null; + } + {{- else }} if (numPages == null || numPages.Value() <= page) { return null; } + {{- end }} {{- end }} {{- end }} diff --git a/templates/templates/unity/tests/Tests/primary/PaginationShould.cs b/templates/templates/unity/tests/Tests/primary/PaginationShould.cs index 31f383d4b..70ce0ada0 100644 --- a/templates/templates/unity/tests/Tests/primary/PaginationShould.cs +++ b/templates/templates/unity/tests/Tests/primary/PaginationShould.cs @@ -5,6 +5,7 @@ using NUnit.Framework; using UnityEngine.TestTools; using System.Collections; +using System.Collections.Generic; public class PaginationShould { @@ -78,6 +79,61 @@ public IEnumerator PaginationLimitOffsetPageBody() }); } + [UnityTest] + public IEnumerator PaginationLimitOffsetPageNumPagesMissing() + { + CommonHelpers.RecordTest("pagination-limit-offset-page-num-pages-missing"); + + yield return CommonHelpers.Await(async () => + { + var sdk = new SDK(); + + // the test service omits numPages on the first page and returns null on + // the second, so termination must fall back to the result length + using ( + var res = await sdk.Pagination.PaginationLimitOffsetPageNumPagesMissingAsync( + page: 1, + limit: 7 + ) + ) + { + Assert.AreEqual(200, res.StatusCode); + Assert.NotNull(res.Res); + Assert.Null(res.Res.NumPages); + CollectionAssert.AreEqual(new List { 0, 1, 2, 3, 4, 5, 6 }, res.Res.ResultArray); + + using (var nextRes = await res.Next()) + { + Assert.NotNull(nextRes); + Assert.AreEqual(200, nextRes.StatusCode); + Assert.NotNull(nextRes.Res); + Assert.Null(nextRes.Res.NumPages); + CollectionAssert.AreEqual( + new List { 7, 8, 9, 10, 11, 12, 13 }, + nextRes.Res.ResultArray + ); + + using (var lastRes = await nextRes.Next()) + { + Assert.NotNull(lastRes); + Assert.AreEqual(200, lastRes.StatusCode); + Assert.NotNull(lastRes.Res); + Assert.AreEqual(3, lastRes.Res.NumPages); + CollectionAssert.AreEqual( + new List { 14, 15, 16, 17, 18, 19 }, + lastRes.Res.ResultArray + ); + + using (var nullRes = await lastRes.Next()) + { + Assert.Null(nullRes); + } + } + } + } + }); + } + [UnityTest] public IEnumerator PaginationLimitOffsetDeepOutputsPageBody() { diff --git a/tests/specs/fragments/uber/pagination-num-pages-missing.yaml b/tests/specs/fragments/uber/pagination-num-pages-missing.yaml new file mode 100644 index 000000000..c585db4e3 --- /dev/null +++ b/tests/specs/fragments/uber/pagination-num-pages-missing.yaml @@ -0,0 +1,67 @@ +openapi: 3.1.0 +security: + - apiKeyAuth: [] + - oauth2: [] + - clientCredentials: [read, write] + - customSchemeAppId: [] + - basicHttp: [] + - accessToken: [] + - {} +paths: + /pagination/limitoffset/page/num_pages_missing: + get: + operationId: paginationLimitOffsetPageNumPagesMissing + servers: + - url: http://localhost:35456 + description: >- + Tests offsetLimit page pagination that declares both a numPages and a + results output when a response does not carry a numeric numPages. The + test service omits numPages from the first page and returns null on the + second, stating the total only on the final page. A missing or null + total must not be treated as the last page: pagination falls back to + the results length and advances until a page is short or empty, so all + three pages are returned and no fourth request is made. + tags: + - pagination + parameters: + - name: page + in: query + required: true + schema: + type: integer + - name: limit + in: query + required: false + schema: + type: integer + responses: + "200": + description: OK + content: + application/json: + schema: + title: res + type: object + properties: + numPages: + type: + - integer + - "null" + resultArray: + type: array + items: + type: integer + required: + - resultArray + x-speakeasy-pagination: + type: offsetLimit + inputs: + - name: page + in: parameters + type: page + - name: limit + in: parameters + type: limit + outputs: + numPages: $.numPages + results: $.resultArray