Merge remote-tracking branch 'origin/main' into csdl2openapi/create-key

Author: HeikoTheissen

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.29.0 - 2025-01-27
+
+### Fixed
+
+- Apply default value `true` for `Capabilities.NavigationRestrictions/RestrictedProperties/TopSupported` and `.../SkipSupported`
+
 ## 0.28.2 - 2024-10-30
 
 ### Fixed

README.md

@@ -34,7 +34,7 @@
 
 <h3>Further Description of this Repository</h3>
 
-The OData TC has published the [OData to OpenAPI Mapping Version 1.0](http://docs.oasis-open.org/odata/odata-openapi/v1.0/odata-openapi-v1.0.html), a recommendation on how to create OpenAPI descriptions for OData services. This project contains two proof-of-concept implementations of that mapping, [one using JavaScript](https://github.com/oasis-tcs/odata-openapi/blob/main/lib), and [one using XSLT](https://github.com/oasis-tcs/odata-openapi/blob/main/tools).
+The OData TC has published the [OData to OpenAPI Mapping Version 1.0](http://docs.oasis-open.org/odata/odata-openapi/v1.0/odata-openapi-v1.0.html), a recommendation on how to create OpenAPI descriptions for OData services. This project contains two proof-of-concept implementations of that mapping, [one using JavaScript](https://github.com/oasis-tcs/odata-openapi/blob/main/lib), and [one using XSLT](https://github.com/oasis-tcs/odata-openapi/blob/main/tools). The latter also evaluates certain "OData V2 style" annotations that are explained [here](https://sap.github.io/odata-vocabularies/docs/v2-annotations.html).
 
 The [`examples` folder](https://github.com/oasis-tcs/odata-openapi/blob/main/examples) contains [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification) descriptions that have been created from the XML `$metadata` documents of live and example OData services with these proof-of-concept implementations.
 

examples/annotations.openapi3.json

@@ -2067,7 +2067,14 @@
                     "ReadOnlySingleton",
                     "TwoReadOnlySet"
                 ],
-                "parameters": [],
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/top"
+                    },
+                    {
+                        "$ref": "#/components/parameters/skip"
+                    }
+                ],
                 "responses": {
                     "200": {
                         "description": "Retrieved entities",

lib/README.md

@@ -51,3 +51,5 @@ Options:
 ## Supported Annotations
 
 The mapping can be fine-tuned via [annotations](https://github.com/oasis-tcs/odata-openapi/blob/main/doc/Annotations.md) in the CSDL (`$metadata`) XML documents.
+
+This tool generates OpenAPI documents for OData V4 services that allow deep insert/upsert only for _containment_ navigation properties. Such OpenAPI documents are suitable for CAP-based services, see also the [`@cap-js/openapi` package](https://github.com/cap-js/openapi) that was forked from this repository.

lib/csdl2openapi.js

@@ -38,6 +38,23 @@ const TITLE_SUFFIX = {
   "-update": " (for update)",
 };
 
+const SYSTEM_QUERY_OPTIONS = [
+  "compute",
+  "expand",
+  "select",
+  "filter",
+  "search",
+  "count",
+  "orderby",
+  "skip",
+  "top",
+  "format",
+  "index",
+  "schemaversion",
+  "skiptoken",
+  "apply",
+];
+
 /**
  * Construct an OpenAPI description from a CSDL document
  * @param {object} csdl CSDL document
@@ -610,8 +627,8 @@ module.exports.csdl2openapi = function (
             (byKey
               ? "entity from "
               : element.$Collection
-              ? "entities from "
-              : "") +
+                ? "entities from "
+                : "") +
             (level > 0 ? "related " : "") +
             name +
             (byKey ? " by key" : ""),
@@ -1073,8 +1090,8 @@ module.exports.csdl2openapi = function (
    */
   function optionSkip(parameters, target, restrictions) {
     const supported =
-      restrictions.SkipSupported !== undefined
-        ? restrictions.SkipSupported
+      Object.keys(restrictions).length > 0
+        ? restrictions.SkipSupported !== false
         : target == null || target[voc.Capabilities.SkipSupported] !== false;
 
     if (supported) {
@@ -1092,8 +1109,8 @@ module.exports.csdl2openapi = function (
    */
   function optionTop(parameters, target, restrictions) {
     const supported =
-      restrictions.TopSupported !== undefined
-        ? restrictions.TopSupported
+      Object.keys(restrictions).length > 0
+        ? restrictions.TopSupported !== false
         : target == null || target[voc.Capabilities.TopSupported] !== false;
 
     if (supported) {
@@ -1714,7 +1731,13 @@ module.exports.csdl2openapi = function (
         type?.$UnderlyingType == "Edm.Stream"
       ) {
         param.in = "query";
-        if (implicitAliases) {
+        if (
+          implicitAliases &&
+          csdl.$Version !== "2.0" &&
+          SYSTEM_QUERY_OPTIONS.includes(p.$Name.toLowerCase())
+        ) {
+          param.name = "@" + p.$Name;
+        } else if (implicitAliases) {
           param.name = p.$Name;
         } else {
           pathSegments.push(p.$Name + "=@" + p.$Name);
@@ -1740,7 +1763,13 @@ module.exports.csdl2openapi = function (
           pathSegments.push(p.$Name + "={" + p.$Name + "}");
           param.in = "path";
         }
-        param.name = p.$Name;
+        if (
+          implicitAliases &&
+          csdl.$Version !== "2.0" &&
+          SYSTEM_QUERY_OPTIONS.includes(p.$Name.toLowerCase())
+        )
+          param.name = "@" + p.$Name;
+        else param.name = p.$Name;
         if (
           !p.$Type ||
           p.$Type === "Edm.String" ||