fix: Support $skiptoken in GET

CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 ## [Unreleased]
 
 ### Added
+- Emit `$skiptoken` query parameter for GET collection endpoints, enabling server-driven paging to be visible in the generated OpenAPI document
 - Added `defaultProtocol` configuration option as fallback if no config is provided.
 ### Changed
 - set `odata` as the service protocol if no protocol is set to match the default behavior of `@sap/cds`. Provide `cds.env.openapi.defaultProtocol = "rest"` to restore old behavior.

lib/compile/csdl.js

@@ -10,7 +10,7 @@ const CDS_TERMS = Object.freeze({
     Authorization: ['Authorizations', 'SecuritySchemes'],
     Capabilities: ['BatchSupport', 'BatchSupported', 'ChangeTracking', 'CountRestrictions', 'DeleteRestrictions', 'DeepUpdateSupport', 'ExpandRestrictions',
         'FilterRestrictions', 'IndexableByKey', 'InsertRestrictions', 'KeyAsSegmentSupported', 'NavigationRestrictions', 'OperationRestrictions',
-        'ReadRestrictions', 'SearchRestrictions', 'SelectSupport', 'SkipSupported', 'SortRestrictions', 'TopSupported', 'UpdateRestrictions'],
+        'ReadRestrictions', 'SearchRestrictions', 'SelectSupport', 'SkipSupported', 'SkipTokenSupported', 'SortRestrictions', 'TopSupported', 'UpdateRestrictions'],
     Core: ['AcceptableMediaTypes', 'Computed', 'ComputedDefaultValue', 'DefaultNamespace', 'Description', 'Example', 'Immutable', 'LongDescription',
         'MediaType', 'OptionalParameter', 'Permissions', 'SchemaVersion'],
     JSON: ['Schema'],

lib/compile/csdl2openapi.js

@@ -90,7 +90,7 @@
  * @param {{ url?: string, servers?: object, odataVersion?: string, scheme?: string, host?: string, basePath?: string, diagram?: boolean, maxLevels?: number, shortActionPaths?: boolean }} options Optional parameters
  * @return {*} OpenAPI description
  */
 module.exports.csdl2openapi = function (
     csdl,
     {
         url: serviceRoot,
@@ -476,7 +476,7 @@
      * @param {number} options.level Number of navigation segments so far
      * @param {string} options.navigationPath Path for finding navigation restrictions
      */
     function pathItems({ paths, prefix, prefixParameters, element, root, sourceName, targetName, target, level, navigationPath }) {
         const name = prefix.substring(prefix.lastIndexOf('/') + 1);
         const type = meta.modelElement(element.$Type);
         const pathItem = {};
@@ -754,7 +754,7 @@
      * @param {boolean} options.byKey Read by key
      * @param {array} options.nonExpandable Non-expandable navigation properties
      */
     function operationRead({ pathItem, element, name, sourceName, targetName, target, level, restrictions, byKey, nonExpandable }) {
         const targetRestrictions = target?.[meta.voc.Capabilities.ReadRestrictions];
         const readRestrictions = restrictions.ReadRestrictions || targetRestrictions || {};
         const readByKeyRestrictions = readRestrictions.ReadByKeyRestrictions;
@@ -804,6 +804,7 @@
             if (collection) {
                 optionTop(operation.parameters, target, restrictions);
                 optionSkip(operation.parameters, target, restrictions);
+                optionSkiptoken(operation.parameters, target);
                 if (csdl.$Version >= '4.0') optionSearch(operation.parameters, target, restrictions);
                 optionFilter(operation.parameters, target, restrictions);
                 optionCount(operation.parameters, target);
@@ -1194,6 +1195,21 @@
         }
     }
 
+    /**
+     * Add parameter for query option $skiptoken
+     * @param {Array} parameters Array of parameters to augment
+     * @param {null | TargetRestrictions} target Target container child of path
+     */
+    function optionSkiptoken(parameters, target) {
+        const supported = target == null || target[meta.voc.Capabilities.SkipTokenSupported] !== false;
+
+        if (supported) {
+            parameters.push({
+                $ref: '#/components/parameters/skiptoken'
+            });
+        }
+    }
+
     /**
      * Add parameter for query option $top
      * @param {Array} parameters Array of parameters to augment
@@ -1224,7 +1240,7 @@
      * @param {*} options.restrictions Navigation property restrictions of navigation segment
      * @param {boolean} [options.byKey=false] Update by key
      */
     function operationUpdate({ pathItem, element, name, sourceName, target, level, restrictions, byKey = false }) {
         const updateRestrictions = restrictions.UpdateRestrictions || target?.[meta.voc.Capabilities.UpdateRestrictions] || {};
         const countRestrictions = target?.[meta.voc.Capabilities.CountRestrictions]?.Countable === false;
         if (updateRestrictions.Updatable !== false && !element[meta.voc.Core.Immutable]) {
@@ -1315,7 +1331,7 @@
      */
     function pathItemsForMediaStream({ paths, prefix, prefixParameters, type, name, sourceName }) {
         if (type.$HasStream) {
             const mediaTypes = type[meta.voc.Core.AcceptableMediaTypes]?.map(t => t['$EnumMember'] ?? t) ?? [];
             const contentTypes = mediaTypes.length > 0 ? mediaTypes : ['*/*'];
             const mediaContent = Object.fromEntries(contentTypes.map(ct => [ct, { schema: { type: 'string', format: 'binary' } }]));
             const lname = splitName(name);
@@ -1645,7 +1661,7 @@
      * @param {string} options.sourceName Name of path source
      * @param {*} [options.actionImport={}] Action import
      */
     function pathItemAction({ paths, prefix, prefixParameters, actionName, overload, sourceName, actionImport = {} }) {
         const name = actionName.indexOf('.') === -1 ? actionName : nameParts(actionName).name;
         const pathItem = {
             post: {
@@ -1735,7 +1751,7 @@
      * @param {string} options.sourceName Name of path source
      * @param {*} [options.functionImport={}] Function Import
      */
     function pathItemFunction({ paths, prefix, prefixParameters, functionName, overload, sourceName, functionImport = {} }) {
         const name = functionName.indexOf('.') === -1 ? functionName : nameParts(functionName).name;
         let parameters = overload.$Parameter || [];
         if (overload.$IsBound) parameters = parameters.slice(1);
@@ -1744,7 +1760,7 @@
 
         const implicitAliases = csdl.$Version > '4.0' || parameters.some(p => p[meta.voc.Core.OptionalParameter]);
 
         parameters.forEach(p => {
             const description = getDescriptionWithFallback(p);
             /** @type {Parameter} */
             const param = {
@@ -2124,7 +2140,7 @@
      * @param {string} options.suffix Suffix for read/create/update
      * @return {*} Map of Schemas Objects
      */
     function schemasForStructuredType({ schemas, qualifier, name, type, suffix }) {
         const schemaName = `${qualifier}.${name}${suffix}`;
         const baseName = `${qualifier}.${name}`;
         const isKey = keyMap(type);
@@ -2140,7 +2156,7 @@
         const properties = propertiesOfStructuredType(type);
         const expandRestrictions = type[meta.voc.Capabilities.ExpandRestrictions] ?? {};
         const nonExpandableProperties = expandRestrictions.NonExpandableProperties ?? [];
         Object.keys(properties).forEach(iName => {
             if (nonExpandableProperties.includes(iName)) {
                 return;
             }
@@ -2264,6 +2280,14 @@
                     minimum: 0
                 }
             },
+            skiptoken: {
+                name: `${queryOptionPrefix}skiptoken`,
+                in: 'query',
+                description: 'Paging - Skip token, see [Server-driven Paging](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ServerDrivenPaging)',
+                schema: {
+                    type: 'string'
+                }
+            },
             count: {
                 name: `${queryOptionPrefix}count`,
                 in: 'query',

test/lib/compile/csdl2openapi.test.js

@@ -570,7 +570,7 @@ describe("Edge cases", () => {
 
     const openapi = lib.csdl2openapi(csdl, {});
     assert.deepStrictEqual(
-      openapi.paths["/sources"].get.parameters[5],
+      openapi.paths["/sources"].get.parameters[6],
       expected_sources_get_param
     );
   });
@@ -1292,6 +1292,7 @@ describe("Edge cases", () => {
             parameters: [
               { $ref: "#/components/parameters/top" },
               { $ref: "#/components/parameters/skip" },
+              { $ref: "#/components/parameters/skiptoken" },
               { $ref: "#/components/parameters/search" },
               {
                 in: "query",
@@ -1474,6 +1475,7 @@ describe("Edge cases", () => {
             parameters: [
               { $ref: "#/components/parameters/top" },
               { $ref: "#/components/parameters/skip" },
+              { $ref: "#/components/parameters/skiptoken" },
               { $ref: "#/components/parameters/search" },
               {
                 in: "query",
@@ -1667,6 +1669,7 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
             parameters: [
               { $ref: "#/components/parameters/top" },
               { $ref: "#/components/parameters/skip" },
+              { $ref: "#/components/parameters/skiptoken" },
               { $ref: "#/components/parameters/search" },
               {
                 in: "query",
@@ -1850,6 +1853,7 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
             parameters: [
               { $ref: "#/components/parameters/top" },
               { $ref: "#/components/parameters/skip" },
+              { $ref: "#/components/parameters/skiptoken" },
               { $ref: "#/components/parameters/search" },
               {
                 in: "query",
@@ -2040,6 +2044,7 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot
             parameters: [
               { $ref: "#/components/parameters/top" },
               { $ref: "#/components/parameters/skip" },
+              { $ref: "#/components/parameters/skiptoken" },
               {
                 in: "query",
                 name: "$search",
@@ -3368,6 +3373,7 @@ describe("CAP / CS01", () => {
             parameters: [
               { $ref: "#/components/parameters/top" },
               { $ref: "#/components/parameters/skip" },
+              { $ref: "#/components/parameters/skiptoken" },
               { $ref: "#/components/parameters/search" },
               {
                 in: "query",