@sap/cds-dk 4.9.5 → 6.0.1

package/lib/compile/openapi/csdl2openapi.js

@@ -10,7 +10,6 @@ var pluralize = require('pluralize')
 // - inject $Name or $$Name into each model element to make parameter passing easier?
 // - allow passing additional files for referenced documents
 // - delta: headers Prefer and Preference-Applied
-// - custom headers and query options - https://issues.oasis-open.org/browse/ODATA-1099
 // - response codes and descriptions - https://issues.oasis-open.org/browse/ODATA-884
 // - inline definitions for Edm.* to make OpenAPI documents self-contained
 // - both "clickable" and freestyle $expand, $select, $orderby - does not work yet, open issue for OpenAPI UI
@@ -51,15 +50,18 @@ module.exports.csdl2openapi = function (
     preProcess(csdl, boundOverloads, derivedTypes, alias, namespace, namespaceUrl, voc);
 
     const entityContainer = csdl.$EntityContainer ? modelElement(csdl.$EntityContainer) : {};
-    const keyAsSegment = entityContainer[voc.Capabilities.KeyAsSegmentSupported];
-    const deepUpdate = entityContainer[voc.Capabilities.DeepUpdateSupport] && entityContainer[voc.Capabilities.DeepUpdateSupport].Supported;
+    const keyAsSegment = entityContainer ? entityContainer[voc.Capabilities.KeyAsSegmentSupported] : {};
+    const deepUpdate = entityContainer ? entityContainer[voc.Capabilities.DeepUpdateSupport] && entityContainer[voc.Capabilities.DeepUpdateSupport].Supported : {};
 
     const openapi = {
         openapi: '3.0.2',
         info: getInfo(csdl, entityContainer),
+        'x-sap-api-type': 'ODATAV4',
+        'x-odata-version': '4.0',
+        'x-sap-shortText': getShortText(csdl, entityContainer),
         servers: getServers(serviceRoot),
-        tags: getTags(entityContainer),
-        paths: getPaths(entityContainer),
+        tags: entityContainer ? getTags(entityContainer) : {},
+        paths: entityContainer ? getPaths(entityContainer) : {},
         components: getComponents(csdl, entityContainer)
     };
     if (!csdl.$EntityContainer) {
@@ -131,10 +133,23 @@ module.exports.csdl2openapi = function (
                 } else {
                     element = modelElement(segments[0].substring(0, open));
                     let args = segments[0].substring(open + 1, segments[0].length - 1);
-                    element = element.find(overload =>
-                        overload.$Kind == 'Action' && overload.$IsBound != true && args == ''
-                        || overload.$Kind == 'Action' && args == (overload.$Parameter[0].$Type || '')
-                        || (overload.$Parameter || []).map(p => { const type = p.$Type || 'Edm.String'; return p.$Collection ? `Collection(${type})` : type }).join(',') == args);
+                    element = element.find(
+                        (overload) =>
+                            (overload.$Kind == "Action" &&
+                                overload.$IsBound != true &&
+                                args == "") ||
+                            (overload.$Kind == "Action" &&
+                                args ==
+                                (overload.$Parameter[0].$Collection
+                                    ? `Collection(${overload.$Parameter[0].$Type})`
+                                    : overload.$Parameter[0].$Type || "")) ||
+                            (overload.$Parameter || [])
+                                .map((p) => {
+                                    const type = p.$Type || "Edm.String";
+                                    return p.$Collection ? `Collection(${type})` : type;
+                                })
+                                .join(",") == args
+                    );
                 }
                 if (!element) {
                     // console.warn(`Invalid annotation target '${target}'`)
@@ -180,9 +195,8 @@ module.exports.csdl2openapi = function (
         const terms = {
             Authorization: ['Authorizations', 'SecuritySchemes'],
             Capabilities: ['BatchSupport', 'BatchSupported', 'ChangeTracking', 'CountRestrictions', 'DeleteRestrictions', 'DeepUpdateSupport', 'ExpandRestrictions',
-                'FilterRestrictions', 'IndexableByKey', 'InsertRestrictions', 'KeyAsSegmentSupported', 'NavigationRestrictions',
-                'SearchRestrictions', 'SelectSupport', 'SkipSupported', 'SortRestrictions',
-                'ReadRestrictions', 'TopSupported', 'UpdateRestrictions'],
+                'FilterRestrictions', 'IndexableByKey', 'InsertRestrictions', 'KeyAsSegmentSupported', 'NavigationRestrictions', 'OperationRestrictions', 
+                'ReadRestrictions', 'SearchRestrictions', 'SelectSupport', 'SkipSupported', 'SortRestrictions', 'TopSupported', 'UpdateRestrictions'],
             Core: ['AcceptableMediaTypes', 'Computed', 'DefaultNamespace', 'Description', 'Example', 'Immutable', 'LongDescription',
                 'OptionalParameter', 'Permissions', 'SchemaVersion'],
             JSON: ['Schema'],
@@ -210,16 +224,33 @@ module.exports.csdl2openapi = function (
     function getInfo(csdl, entityContainer) {
         const namespace = csdl.$EntityContainer ? nameParts(csdl.$EntityContainer).qualifier : null;
         const containerSchema = csdl.$EntityContainer ? csdl[namespace] : {};
-        const description = (
-            entityContainer[voc.Core.LongDescription]
-            || containerSchema[voc.Core.LongDescription]
-            || 'This service is located at [' + serviceRoot + '/]('
-            + serviceRoot.replace(/\(/g, '%28').replace(/\)/g, '%29') + '/)'
-        ) + (diagram ? getResourceDiagram(csdl, entityContainer) : '');
+        let description;
+        if (entityContainer && entityContainer[voc.Core.LongDescription]) {
+            description = entityContainer[voc.Core.LongDescription];
+        }
+        else if (containerSchema && containerSchema[voc.Core.LongDescription]) {
+            description = containerSchema[voc.Core.LongDescription];
+        }
+        else {
+            description = ('This service is located at [' + serviceRoot + '/](' 
+            + serviceRoot.replace(/\(/g, '%28').replace(/\)/g, '%29') + '/)');
+        }
+        description += (diagram ? getResourceDiagram(csdl, entityContainer) : '');
+        let title;
+        if (entityContainer && entityContainer[voc.Core.Description]) {
+            title = entityContainer[voc.Core.Description];
+        }
+        else if (containerSchema && containerSchema[voc.Core.Description]) {
+            title = containerSchema[voc.Core.Description];
+        }
+        else if (csdl.$EntityContainer) {
+            title = 'Service for namespace ' + namespace;
+        }
+        else {
+            title = 'OData CSDL document';
+        }
         return {
-            title: entityContainer[voc.Core.Description]
-                || containerSchema[voc.Core.Description]
-                || (csdl.$EntityContainer ? 'Service for namespace ' + namespace : 'OData CSDL document'),
+            title: title, 
             description: csdl.$EntityContainer ? description : '',
             version: containerSchema[voc.Core.SchemaVersion] || ''
         };
@@ -349,6 +380,31 @@ module.exports.csdl2openapi = function (
         return schema ? schema[q.name] : null;
     }
 
+    /**
+     * Construct the short text
+     * @param {object} csdl CSDL document
+     * @param {object} entityContainer Entity Container object
+     * @return {string} short text
+     */
+    function getShortText(csdl, entityContainer) {
+        const namespace = csdl.$EntityContainer ? nameParts(csdl.$EntityContainer).qualifier : null;
+        const containerSchema = csdl.$EntityContainer ? csdl[namespace] : {};
+        let shortText;
+        if (entityContainer && entityContainer[voc.Core.Description]) {
+            shortText = entityContainer[voc.Core.Description];
+        }
+        else if (containerSchema && containerSchema[voc.Core.Description]) {
+            shortText = containerSchema[voc.Core.Description];
+        }
+        else if (csdl.$EntityContainer) {
+            shortText = 'Service for namespace ' + namespace;
+        }
+        else {
+            shortText = 'OData CSDL document';
+        }
+        return shortText;
+    }
+
     /**
      * Construct an array of Server Objects
      * @param {object} csdl The CSDL document
@@ -552,6 +608,7 @@ module.exports.csdl2openapi = function (
             };
             if (insertRestrictions.LongDescription) pathItem.post.description = insertRestrictions.LongDescription;
             if (targetName && sourceName != targetName) pathItem.post.tags.push(targetName);
+            customParameters(pathItem.post, insertRestrictions);
         }
     }
 
@@ -629,6 +686,7 @@ module.exports.csdl2openapi = function (
             }
             if (descriptions.LongDescription) operation.description = descriptions.LongDescription;
             if (target && sourceName != targetName) operation.tags.push(targetName);
+            customParameters(operation, byKey ? readByKeyRestrictions || readRestrictions : readRestrictions);
 
             if (collection) {
                 optionTop(operation.parameters, target, restrictions);
@@ -646,6 +704,47 @@ module.exports.csdl2openapi = function (
         }
     }
 
+    /**
+     * Add custom headers and query options
+     * @param {object} operation Operation object to augment
+     * @param {object} restrictions Restrictions for operation
+     */
+    function customParameters(operation, restrictions) {
+        if (
+            !operation.parameters &&
+            (restrictions.CustomHeaders || restrictions.CustomQueryOptions)
+        )
+            operation.parameters = [];
+        for (const custom of restrictions.CustomHeaders || []) {
+            operation.parameters.push(customParameter(custom, "header"));
+        }
+
+        for (const custom of restrictions.CustomQueryOptions || []) {
+            operation.parameters.push(customParameter(custom, "query"));
+        }
+    }
+
+    /**
+     * Construct custom parameter
+     * @param {object} custom custom parameter in OData format
+     * @param {string} location "header" or "query"
+     */
+    function customParameter(custom, location) {
+        return {
+            name: custom.Name,
+            in: location,
+            required: custom.Required || false,
+            ...(custom.Description && { description: custom.Description }),
+            schema: {
+                type: "string",
+                ...(custom.DocumentationURL && {
+                    externalDocs: { url: custom.DocumentationURL },
+                }),
+                //TODO: Examples
+            },
+        };
+    }
+
     /**
      * Add parameter for query option $count
      * @param {Array} parameters Array of parameters to augment
@@ -681,7 +780,10 @@ module.exports.csdl2openapi = function (
                 parameters.push({
                     name: queryOptionPrefix + 'expand',
                     description: (targetRestrictions && targetRestrictions[voc.Core.Description])
-                        || 'Expand related entities, see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionexpand)',
+                        || 'The value of $expand query option is a comma-separated list of navigation property names, \
+stream property names, or $value indicating the stream content of a media-entity. \
+The corresponding related entities and stream values will be represented inline, \
+see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionexpand)',
                     in: 'query',
                     explode: false,
                     schema: {
@@ -1015,7 +1117,7 @@ module.exports.csdl2openapi = function (
 
         if (updateRestrictions.Updatable !== false) {
             const type = modelElement(element.$Type);
-            pathItem.patch = {
+            const operation = {
                 summary: updateRestrictions.Description || operationSummary('Change', name, sourceName, level, element.$Collection, byKey),
                 tags: [sourceName],
                 requestBody: {
@@ -1029,7 +1131,10 @@ module.exports.csdl2openapi = function (
                 },
                 responses: response(204, 'Success')
             };
-            if (updateRestrictions.LongDescription) pathItem.patch.description = updateRestrictions.LongDescription;
+            if (updateRestrictions.LongDescription) operation.description = updateRestrictions.LongDescription;
+            customParameters(operation, updateRestrictions);
+            const updateMethod = updateRestrictions.UpdateMethod ? updateRestrictions.UpdateMethod.toLowerCase() : "patch";
+            pathItem[updateMethod] = operation;
         }
     }
 
@@ -1054,6 +1159,7 @@ module.exports.csdl2openapi = function (
                 responses: response(204, 'Success')
             };
             if (deleteRestrictions.LongDescription) pathItem.delete.description = deleteRestrictions.LongDescription;
+            customParameters(pathItem.delete, deleteRestrictions);
         }
     }
 
@@ -1275,7 +1381,7 @@ module.exports.csdl2openapi = function (
         };
         const description = actionImport[voc.Core.LongDescription] || overload[voc.Core.LongDescription];
         if (description) pathItem.post.description = description;
-        if (prefixParameters.length > 0) pathItem.post.parameters = prefixParameters;
+        if (prefixParameters.length > 0) pathItem.post.parameters = [...prefixParameters];
         let parameters = overload.$Parameter || [];
         if (overload.$IsBound) parameters = parameters.slice(1);
         if (parameters.length > 0) {
@@ -1293,6 +1399,7 @@ module.exports.csdl2openapi = function (
                 }
             }
         }
+        customParameters(pathItem.post, overload[voc.Capabilities.OperationRestrictions] || {});
         paths[prefix] = pathItem;
     }
 
@@ -1385,6 +1492,7 @@ module.exports.csdl2openapi = function (
         };
         const iDescription = functionImport[voc.Core.LongDescription] || overload[voc.Core.LongDescription];
         if (iDescription) pathItem.get.description = iDescription;
+        customParameters(pathItem.get, overload[voc.Capabilities.OperationRestrictions] || {});
         paths[prefix + pathParameters] = pathItem;
     }
 
@@ -1638,6 +1746,9 @@ module.exports.csdl2openapi = function (
         Object.keys(properties).forEach(iName => {
             const property = properties[iName];
             allProperties[iName] = getSchema(property);
+            if ((Object.prototype.hasOwnProperty.call(property, '@Common.FieldControl')) && property['@Common.FieldControl'] === 'Mandatory') {
+                required.push(iName)
+            }
             if (property.$Kind == 'NavigationProperty') {
                 if (property.$Collection) {
                     allProperties[`${iName}@${csdl.$Version === '4.0' ? 'odata.' : ''}count`] = ref('count');
@@ -1878,8 +1989,7 @@ module.exports.csdl2openapi = function (
                 break;
             case 'Edm.Decimal':
                 s = {
-                    anyOf: [{ type: 'number' }, { type: 'string' }],
-                    format: 'decimal',
+                    anyOf: [{ type: 'number', format: 'decimal'}, { type: 'string' }],
                     example: 0
                 };
                 // eslint-disable-next-line no-case-declarations
@@ -1887,21 +1997,20 @@ module.exports.csdl2openapi = function (
                 if (scale !== null) {
                     // Node.js 12.13.0 has problems with negative exponents, 10 ** -5 --> 0.000009999999999999999
                     if (scale <= 0)
-                        s.multipleOf = 10 ** -scale;
+                        s.anyOf[0].multipleOf = 10 ** -scale;
                     else
-                        s.multipleOf = 1 / 10 ** scale;
+                        s.anyOf[0].multipleOf = 1 / 10 ** scale;
                 }
                 if (element.$Precision < 16) {
                     let limit = 10 ** (element.$Precision - scale);
                     let delta = 10 ** -scale;
-                    s.maximum = limit - delta;
-                    s.minimum = -s.maximum;
+                    s.anyOf[0].maximum = limit - delta;
+                    s.anyOf[0].minimum = -s.anyOf[0].maximum;
                 }
                 break;
             case 'Edm.Double':
                 s = {
-                    anyOf: [{ type: 'number' }, { type: 'string' }],
-                    format: 'double',
+                    anyOf: [{ type: 'number', format: 'double' }, { type: 'string' }],
                     example: 3.14
                 };
                 break;
@@ -1938,8 +2047,7 @@ module.exports.csdl2openapi = function (
                 break;
             case 'Edm.Int64':
                 s = {
-                    anyOf: [{ type: 'integer' }, { type: 'string' }],
-                    format: 'int64',
+                    anyOf: [{ type: 'integer', format: 'int64' }, { type: 'string' }],
                     example: "42"
                 };
                 break;
@@ -1956,8 +2064,7 @@ module.exports.csdl2openapi = function (
                 break;
             case 'Edm.Single':
                 s = {
-                    anyOf: [{ type: 'number' }, { type: 'string' }],
-                    format: 'float',
+                    anyOf: [{ type: 'number', format: 'float' }, { type: 'string' }],
                     example: 3.14
                 };
                 break;
@@ -2037,6 +2144,7 @@ module.exports.csdl2openapi = function (
             if (element.$Nullable) {
                 if (!s.anyOf && !s.allOf) s.type = "string";
                 if (s.format) s.format += ",null";
+                if (s.anyOf && s.anyOf[0].format) s.anyOf[0].format += ",null";
                 s.default = "null";
                 if (s.pattern) {
                     s.pattern = s.pattern.replace(/^\^/, "^(null|");
@@ -2047,13 +2155,13 @@ module.exports.csdl2openapi = function (
 
         if (element[voc.Validation.Maximum] != undefined) {
             if (s.$ref) s = { allOf: [s] };
-            s.maximum = element[voc.Validation.Maximum];
+            s.anyOf[0].maximum = element[voc.Validation.Maximum];
             if (element[voc.Validation.Maximum + voc.Validation.Exclusive]) s.exclusiveMaximum = true;
         }
 
         if (element[voc.Validation.Minimum] != undefined) {
             if (s.$ref) s = { allOf: [s] };
-            s.minimum = element[voc.Validation.Minimum];
+            s.anyOf[0].minimum = element[voc.Validation.Minimum];
             if (element[voc.Validation.Minimum + voc.Validation.Exclusive]) s.exclusiveMinimum = true;
         }
 
@@ -2108,7 +2216,7 @@ module.exports.csdl2openapi = function (
             name = nsp + '.' + parts.name;
             url = namespaceUrl[nsp] || '';
             //TODO: introduce better way than guessing
-            if (url.endsWith('.xml')) url = url.substr(0, url.length - 3) + 'openapi3.json';
+            if (url.endsWith('.xml')) url = url.substring(0, url.length - 3) + "openapi3.json";
         }
         return {
             $ref: url + '#/components/schemas/' + name + suffix
@@ -2121,7 +2229,7 @@ module.exports.csdl2openapi = function (
      * @param {object} entityContainer Entity Container object
      */
     function getSecuritySchemes(components, entityContainer) {
-        const authorizations = entityContainer[voc.Authorization.Authorizations] || [];
+        const authorizations = entityContainer && entityContainer[voc.Authorization.Authorizations] ? entityContainer[voc.Authorization.Authorizations] : [];
         const schemes = {};
         const location = { Header: 'header', QueryOption: 'query', Cookie: 'cookie' };
         authorizations.forEach(auth => {
@@ -2129,7 +2237,7 @@ module.exports.csdl2openapi = function (
             const flow = {};
             if (auth.Description) scheme.description = auth.Description;
             const qualifiedType = auth['@type'] || auth['@odata.type']
-            const type = qualifiedType.substr(qualifiedType.lastIndexOf('.') + 1);
+            const type = qualifiedType.substring(qualifiedType.lastIndexOf(".") + 1);
             let unknown = false
             switch (type) {
                 case 'ApiKey':
@@ -2197,7 +2305,7 @@ module.exports.csdl2openapi = function (
      * @param {object} entityContainer Entity Container object
      */
     function security(openapi, entityContainer) {
-        const securitySchemes = entityContainer[voc.Authorization.SecuritySchemes] || [];
+        const securitySchemes = entityContainer && entityContainer[voc.Authorization.SecuritySchemes] ? entityContainer[voc.Authorization.SecuritySchemes] : [];
         if (securitySchemes.length > 0) openapi.security = [];
         securitySchemes.forEach(scheme => {
             const s = {};

package/lib/compile/openapi/index.js

@@ -1,5 +1,5 @@
-const csdl2openapi = require('./csdl2openapi');
-const cds = require('@sap/cds');
+const csdl2openapi = require('./csdl2openapi')
+const cds = require('../../cds')
 
 module.exports = function processor(csn, options = {}) {
 

package/lib/compile/to-xsuaa.js

@@ -1,4 +1,4 @@
-const cds = require ('@sap/cds')
+const cds = require('../cds')
 const fs = require('fs')
 const path = require('path')
 
@@ -99,7 +99,8 @@ module.exports = function compile_to_xsuaa (model, options) {
         valueRequired: false
       }
     }),
-    'role-templates': roleTemplates
+    'role-templates': roleTemplates,
+    'authorities-inheritance': false
   }
   return mergeConfig(base, generated)
 }