diff --git a/lib/compile/csdl2openapi.js b/lib/compile/csdl2openapi.js index f1d7145..0dcbcc2 100644 --- a/lib/compile/csdl2openapi.js +++ b/lib/compile/csdl2openapi.js @@ -277,25 +277,15 @@ module.exports.csdl2openapi = function ( description = containerSchema[voc.Core.LongDescription]; } else { - description = ('This service is located at [' + serviceRoot + '/](' - + serviceRoot.replace(/\(/g, '%28').replace(/\)/g, '%29') + '/)'); + description = "Use @Core.LongDescription: '...' on your CDS service to provide a meaningful description."; } description += (diagram ? getResourceDiagram(csdl, entityContainer) : ''); let title; if (entityContainer && entityContainer[voc.Common.Label]) { title = entityContainer[voc.Common.Label]; } - else 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'; + title = "Use @title: '...' on your CDS service to provide a meaningful title."; } return { title: title, @@ -462,11 +452,8 @@ module.exports.csdl2openapi = function ( 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'; + shortText = "Use @Core.Description: '...' on your CDS service to provide a meaningful short text."; } return shortText; } diff --git a/test/lib/compile/csdl2openapi.test.js b/test/lib/compile/csdl2openapi.test.js index 4dfec6a..c6f90db 100644 --- a/test/lib/compile/csdl2openapi.test.js +++ b/test/lib/compile/csdl2openapi.test.js @@ -89,14 +89,14 @@ describe('Edge cases', function () { const expected = { openapi: '3.0.2', info: { - title: 'OData CSDL document', + title: "Use @title: '...' on your CDS service to provide a meaningful title.", description: '', version: '' }, paths: {}, 'x-odata-version': '4.01', 'x-sap-api-type': 'ODATAV4', - 'x-sap-shortText': 'OData CSDL document', + 'x-sap-shortText': "Use @Core.Description: '...' on your CDS service to provide a meaningful short text.", components: { schemas: {} } }; const openapi = lib.csdl2openapi(csdl, {}); @@ -120,14 +120,14 @@ describe('Edge cases', function () { const expected = { openapi: '3.0.2', info: { - title: 'OData CSDL document', + title: "Use @title: '...' on your CDS service to provide a meaningful title.", description: '', version: '' }, paths: {}, 'x-odata-version': '4.01', 'x-sap-api-type': 'ODATAV4', - 'x-sap-shortText': 'OData CSDL document', + 'x-sap-shortText': "Use @Core.Description: '...' on your CDS service to provide a meaningful short text.", components: { schemas: {}, } @@ -163,13 +163,13 @@ describe('Edge cases', function () { const expected = { openapi: "3.0.2", info: { - title: 'OData CSDL document', + title: "Use @title: '...' on your CDS service to provide a meaningful title.", description: "", version: "", }, "x-odata-version": "4.01", "x-sap-api-type": "ODATAV4", - "x-sap-shortText": "OData CSDL document", + "x-sap-shortText": "Use @Core.Description: '...' on your CDS service to provide a meaningful short text.", paths: {}, components: { schemas: {}, @@ -1991,7 +1991,7 @@ see [Expand](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-prot assert.deepStrictEqual(actual.paths['/roots/act'].post, expected.paths['/roots/act'].post, 'POST /roots/act'); assert.deepStrictEqual(actual.info.description.split("\n"), [ - "This service is located at [https://localhost/service-root/](https://localhost/service-root/)", + "Use @Core.LongDescription: '...' on your CDS service to provide a meaningful description.", "", "## Entity Data Model", "![ER Diagram](https://yuml.me/diagram/class/[root{bg:lightslategray}],[root]->[other],[other{bg:lightslategray}],[act{bg:lawngreen}]->[root],[act{bg:lawngreen}]in->[root],[others%20{bg:lawngreen}]++-*>[other],[roots%20{bg:lawngreen}]++-*>[root])", diff --git a/test/lib/compile/data/TripPin.json b/test/lib/compile/data/TripPin.json index ebd9bb7..d71910e 100644 --- a/test/lib/compile/data/TripPin.json +++ b/test/lib/compile/data/TripPin.json @@ -1,6 +1,13 @@ { "$Version": "4.0", "$Reference": { + "https://sap.github.io/odata-vocabularies/vocabularies/Common.xml": { + "$Include": [ + { + "$Namespace": "com.sap.vocabularies.Common.v1" + } + ] + }, "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": { "$Include": [ { @@ -445,7 +452,9 @@ "ResetDataSource": { "$Action": "Microsoft.OData.SampleService.Models.TripPin.ResetDataSource" }, - "@Org.OData.Core.V1.Description": "TripPin service is a sample service for OData V4." + "@com.sap.vocabularies.Common.v1.Label": "TripPin service is a sample service for OData V4.", + "@Org.OData.Core.V1.Description": "TripPin service is a sample service for OData V4.", + "@Org.OData.Core.V1.LongDescription": "This service is located at [https://services.odata.org/V4/(S(cnbm44wtbc1v5bgrlek5lpcc))/TripPinServiceRW/](https://services.odata.org/V4/%28S%28cnbm44wtbc1v5bgrlek5lpcc%29%29/TripPinServiceRW/)" }, "$Annotations": { "Microsoft.OData.SampleService.Models.TripPin.DefaultContainer": { @@ -486,4 +495,4 @@ } }, "$EntityContainer": "Microsoft.OData.SampleService.Models.TripPin.DefaultContainer" -} \ No newline at end of file +} diff --git a/test/lib/compile/data/annotations.json b/test/lib/compile/data/annotations.json index 7eefbce..684dc2c 100644 --- a/test/lib/compile/data/annotations.json +++ b/test/lib/compile/data/annotations.json @@ -1,6 +1,14 @@ { "$Version": "4.01", "$Reference": { + "https://sap.github.io/odata-vocabularies/vocabularies/Common.xml": { + "$Include": [ + { + "$Alias": "Common", + "$Namespace": "com.sap.vocabularies.Common.v1" + } + ] + }, "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": { "$Include": [ { @@ -156,6 +164,9 @@ }, "Container": { "$Kind": "EntityContainer", + "@Common.Label": "Service for namespace Supported.Annotations", + "@Core.Description": "Service for namespace Supported.Annotations", + "@Core.LongDescription": "This service is located at [https://localhost/service-root/](https://localhost/service-root/)", "@Capabilities.BatchSupported": false, "AllSet": { "$Collection": true, @@ -488,4 +499,4 @@ } }, "$EntityContainer": "Supported.Annotations.Container" -} \ No newline at end of file +} diff --git a/test/lib/compile/data/authorization.json b/test/lib/compile/data/authorization.json index ccfab09..02ad2b6 100644 --- a/test/lib/compile/data/authorization.json +++ b/test/lib/compile/data/authorization.json @@ -1,6 +1,23 @@ { "$Version": "4.0", "$Reference": { + "https://sap.github.io/odata-vocabularies/vocabularies/Common.xml": { + "$Include": [ + { + "$Alias": "Common", + "$Namespace": "com.sap.vocabularies.Common.v1" + } + ] + }, + "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": { + "$Include": [ + { + "$Namespace": "Org.OData.Core.V1", + "$Alias": "Core", + "@Core.DefaultNamespace": true + } + ] + }, "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Authorization.V1.json": { "$Include": [ { @@ -24,6 +41,9 @@ }, "Container": { "$Kind": "EntityContainer", + "@Common.Label": "Service for namespace auth.example", + "@Core.Description": "Service for namespace auth.example", + "@Core.LongDescription": "This service is located at [https://localhost/service-root/](https://localhost/service-root/)", "People": { "$Collection": true, "$Type": "self.Person" @@ -122,4 +142,4 @@ } }, "$EntityContainer": "auth.example.Container" -} \ No newline at end of file +} diff --git a/test/lib/compile/data/containment.json b/test/lib/compile/data/containment.json index fe3116e..d440f50 100644 --- a/test/lib/compile/data/containment.json +++ b/test/lib/compile/data/containment.json @@ -1,6 +1,14 @@ { "$Version": "4.01", "$Reference": { + "https://sap.github.io/odata-vocabularies/vocabularies/Common.xml": { + "$Include": [ + { + "$Alias": "Common", + "$Namespace": "com.sap.vocabularies.Common.v1" + } + ] + }, "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": { "$Include": [ { @@ -231,6 +239,9 @@ }, "Container": { "$Kind": "EntityContainer", + "@Common.Label": "Service for namespace Containment", + "@Core.Description": "Service for namespace Containment", + "@Core.LongDescription": "This service is located at [https://localhost/service-root/](https://localhost/service-root/)", "@Capabilities.BatchSupported": false, "Wholes": { "$Collection": true, @@ -371,4 +382,4 @@ } }, "$EntityContainer": "Containment.Container" -} \ No newline at end of file +} diff --git a/test/lib/compile/data/csdl-16.1.json b/test/lib/compile/data/csdl-16.1.json index 819dc59..2ff347a 100644 --- a/test/lib/compile/data/csdl-16.1.json +++ b/test/lib/compile/data/csdl-16.1.json @@ -1,6 +1,11 @@ { "$Version": "4.01", "$Reference": { + "https://sap.github.io/odata-vocabularies/vocabularies/Common.xml": { + "$Include": [ + { "$Alias": "Common", "$Namespace": "com.sap.vocabularies.Common.v1" } + ] + }, "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": { "$Include": [ { @@ -164,6 +169,9 @@ ], "DemoService": { "$Kind": "EntityContainer", + "@Common.Label": "Service for namespace ODataDemo", + "@Core.Description": "Service for namespace ODataDemo", + "@Core.LongDescription": "This service is located at [https://localhost/service-root/](https://localhost/service-root/)", "Products": { "$Collection": true, "$Type": "ODataDemo.Product", @@ -208,4 +216,4 @@ } }, "$EntityContainer": "ODataDemo.DemoService" -} \ No newline at end of file +} diff --git a/test/lib/compile/data/custom-parameters.json b/test/lib/compile/data/custom-parameters.json index adda16c..b6792fd 100644 --- a/test/lib/compile/data/custom-parameters.json +++ b/test/lib/compile/data/custom-parameters.json @@ -1,6 +1,14 @@ { "$Version": "4.01", "$Reference": { + "https://sap.github.io/odata-vocabularies/vocabularies/Common.xml": { + "$Include": [ + { + "$Alias": "Common", + "$Namespace": "com.sap.vocabularies.Common.v1" + } + ] + }, "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.json": { "$Include": [ { @@ -98,6 +106,9 @@ ], "box": { "$Kind": "EntityContainer", + "@Common.Label": "Service for namespace custom.parameters", + "@Core.Description": "Service for namespace custom.parameters", + "@Core.LongDescription": "This service is located at [https://localhost/service-root/](https://localhost/service-root/)", "@Capabilities.KeyAsSegmentSupported": true, "ents": { "$Collection": true, @@ -483,4 +494,4 @@ } }, "$EntityContainer": "custom.parameters.box" -} \ No newline at end of file +} diff --git a/test/lib/compile/data/descriptions.json b/test/lib/compile/data/descriptions.json index b9e9d3a..1fd9a5a 100644 --- a/test/lib/compile/data/descriptions.json +++ b/test/lib/compile/data/descriptions.json @@ -1,6 +1,14 @@ { "$Version": "4.01", "$Reference": { + "https://sap.github.io/odata-vocabularies/vocabularies/Common.xml": { + "$Include": [ + { + "$Alias": "Common", + "$Namespace": "com.sap.vocabularies.Common.v1" + } + ] + }, "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": { "$Include": [ { @@ -269,6 +277,7 @@ }, "$Annotations": { "self.Default": { + "@Common.Label": "Container - Label", "@Core.Description": "Container - Description", "@Core.LongDescription": "Container - LongDescription" }, diff --git a/test/lib/compile/data/descriptions.openapi3.json b/test/lib/compile/data/descriptions.openapi3.json index e9f5da8..ae33070 100644 --- a/test/lib/compile/data/descriptions.openapi3.json +++ b/test/lib/compile/data/descriptions.openapi3.json @@ -1,7 +1,7 @@ { "openapi": "3.0.2", "info": { - "title": "Container - Description", + "title": "Container - Label", "description": "Container - LongDescription\n\n## Entity Data Model\n![ER Diagram](https://yuml.me/diagram/class/[entity{bg:lightslategray}],[entity]++-*>[subEntity],[entity]-*>[entity],[subEntity{bg:lightslategray}],[functionimport_no_descriptions{bg:lawngreen}],[functionimport_ext{bg:lawngreen}],[functionimport{bg:lawngreen}],[actionimport_no_descriptions{bg:lawngreen}],[actionimport_ext{bg:lawngreen}],[actionimport{bg:lawngreen}],[single_ext%20{bg:lawngreen}]++->[entity],[single%20{bg:lawngreen}]++-0..1>[entity],[entities_ext%20{bg:lawngreen}]++-*>[entity],[entities%20{bg:lawngreen}]++-*>[entity])\n\n### Legend\n![Legend](https://yuml.me/diagram/plain;dir:TB;scale:60/class/[External.Type{bg:whitesmoke}],[ComplexType],[EntityType{bg:lightslategray}],[EntitySet/Singleton/Operation{bg:lawngreen}])", "version": "0.0.1" }, @@ -3635,4 +3635,4 @@ } } } -} \ No newline at end of file +} diff --git a/test/lib/compile/openapi.test.js b/test/lib/compile/openapi.test.js index 4de5032..106bbe2 100644 --- a/test/lib/compile/openapi.test.js +++ b/test/lib/compile/openapi.test.js @@ -186,11 +186,10 @@ describe('OpenAPI export', () => { ); let openapi = toOpenApi(csn, { service: 'A' }); expect(openapi).toMatchObject({ servers: [{ url: '/a' }] }); - expect(openapi.info.description).toMatch(/\/a/i) + expect(openapi.info.description).toBe("Use @Core.LongDescription: '...' on your CDS service to provide a meaningful description.") openapi = toOpenApi(csn, { service: 'A', 'openapi:url': 'http://foo.bar:8080' }); expect(openapi).toMatchObject({ servers: [{ url: 'http://foo.bar:8080' }] }); - expect(openapi.info.description).toMatch(/http:\/\/foo.bar:8080/i) openapi = toOpenApi(csn, { service: 'A', 'openapi:url': 'http://foo.bar:8080//${service-path}/foo' }); expect(openapi).toMatchObject({ servers: [{ url: 'http://foo.bar:8080/a/foo' }] }); @@ -392,4 +391,4 @@ describe('OpenAPI export', () => { expect(openAPI.externalDocs.url).toBe('https://help.sap.com/docs/product/123.html'); } ); -}); \ No newline at end of file +});