chgeo/cds-swagger-ui-express

Swagger UI for CAP services

Github Stats

cds-swagger-ui-express's Issues

Typescript-Support cds-swagger-ui-express

Kindly guide me how to use cds-swagger-ui-express with Tyepscript
Thanks in advance

Open API Preview link missing for service annotated with `@protocol: rest`

Hi @chgeo,

I would think that #51 should have solved this issue, but I've added cds-swagger-ui-express 0.8.0 and see this result:

The OData V4 Service provides a link "Open API Preview" but the Service annotated with @protocol: 'rest' does not. Running:

cds compile srv --service all -o docs --to openapi

Works fine for the rest Service.

Best Regards
Gregor

cds: not found error when deploying service to production

I kept the server.js to a minimum and in line with the documentation. If I only add the cds-swagger-ui-express package to the development dependencies, I receive the error shown below in a production deployment.

Changing the package to a "full" dependency fixes the problem, so I would suggest at least changing the documentation to reflect that.

server.js

const cds = require('@sap/cds')
module.exports = cds.server

console.log('MST Environment Type: ' + process.env.NODE_ENV)
if (process.env.NODE_ENV !== 'production') {
  const cds_swagger = require('cds-swagger-ui-express')
  cds.on('bootstrap', app => app.use(cds_swagger()))
}

service log file

 2021-10-14T13:51:01.61-0700 [STG/0] OUT Uploading droplet, build artifacts cache...
   2021-10-14T13:51:01.61-0700 [STG/0] OUT Uploading droplet...
   2021-10-14T13:51:01.62-0700 [STG/0] OUT Uploading build artifacts cache...
   2021-10-14T13:51:01.66-0700 [STG/0] OUT Uploaded build artifacts cache (225B)
   2021-10-14T13:51:02.92-0700 [API/52] OUT Creating droplet for app with guid e43383fa-61f5-476c-bdd7-61a11c24ac5d
   2021-10-14T13:51:06.15-0700 [STG/0] OUT Uploaded droplet (86.3M)
   2021-10-14T13:51:06.16-0700 [STG/0] OUT Uploading complete
   2021-10-14T13:51:06.30-0700 [STG/0] OUT Cell f5a8de1f-45ae-42d0-b8d2-bad0f239865b stopping instance 7af596e1-f9a9-42b8-895d-6a222fc8925b
   2021-10-14T13:51:06.30-0700 [STG/0] OUT Cell f5a8de1f-45ae-42d0-b8d2-bad0f239865b destroying container for instance 7af596e1-f9a9-42b8-895d-6a222fc8925b
   2021-10-14T13:51:07.06-0700 [STG/0] OUT Cell f5a8de1f-45ae-42d0-b8d2-bad0f239865b successfully destroyed container for instance 7af596e1-f9a9-42b8-895d-6a222fc8925b
   2021-10-14T13:51:13.68-0700 [API/1] OUT Updated app with guid e43383fa-61f5-476c-bdd7-61a11c24ac5d ({:droplet_guid=>"ca6a041c-c803-4825-882d-9853ce893098"})
   2021-10-14T13:51:14.40-0700 [API/44] OUT Creating revision for app with guid e43383fa-61f5-476c-bdd7-61a11c24ac5d
   2021-10-14T13:51:14.48-0700 [API/44] OUT Starting app with guid e43383fa-61f5-476c-bdd7-61a11c24ac5d
   2021-10-14T13:51:14.73-0700 [CELL/0] OUT Cell 2df9ad23-26f8-49d7-b4f5-70cbf2810414 creating container for instance 8a7e4f82-08a5-4561-618a-f438
   2021-10-14T13:51:15.06-0700 [CELL/0] OUT Cell 2df9ad23-26f8-49d7-b4f5-70cbf2810414 successfully created container for instance 8a7e4f82-08a5-4561-618a-f438
   2021-10-14T13:51:15.20-0700 [CELL/0] OUT Downloading droplet...
   2021-10-14T13:51:19.12-0700 [CELL/0] OUT Downloaded droplet (86.3M)
   2021-10-14T13:51:19.12-0700 [CELL/0] OUT Starting health monitoring of container
   2021-10-14T13:51:19.80-0700 [APP/PROC/WEB/0] OUT > [email protected] start
   2021-10-14T13:51:19.80-0700 [APP/PROC/WEB/0] OUT > cds run
   2021-10-14T13:51:19.81-0700 [APP/PROC/WEB/0] ERR sh: 1: cds: not found
   2021-10-14T13:51:19.81-0700 [APP/PROC/WEB/0] ERR npm notice
   2021-10-14T13:51:19.81-0700 [APP/PROC/WEB/0] ERR npm notice New major version of npm available! 7.13.0 -> 8.0.0
   2021-10-14T13:51:19.81-0700 [APP/PROC/WEB/0] ERR npm notice Changelog: <https://github.com/npm/cli/releases/tag/v8.0.0>
   2021-10-14T13:51:19.81-0700 [APP/PROC/WEB/0] ERR npm notice Run `npm install -g [email protected]` to update!
   2021-10-14T13:51:19.81-0700 [APP/PROC/WEB/0] ERR npm notice
   2021-10-14T13:51:19.82-0700 [APP/PROC/WEB/0] OUT Exit status 127

Make this project a CDS Plugin Package

Following the documentation at cds-plugins this package should be converted into a CDS Plugin.

TypeError: Cannot redefine property: _log with NodeJS 18

Hello,

I'm not 100% sure if cds-swagger-ui-express is responsible for this behaviour but, when we launch our CAP applications with NodeJS 18 we get this error:

TypeError: Cannot redefine property: _log
at Function.defineProperties ()
at Object. (C:\Workspaces\asd\node_modules@sap\cds-dk\lib\cds.js:4:25)
at Module._compile (node:internal/modules/cjs/loader:1254:14)
at Module._extensions..js (node:internal/modules/cjs/loader:1308:10)
at Module.load (node:internal/modules/cjs/loader:1117:32)
at Module._load (node:internal/modules/cjs/loader:958:12)
at Module.require (node:internal/modules/cjs/loader:1141:19)
at require (node:internal/modules/cjs/helpers:110:18)
at Object. (C:\Workspaces\asd\node_modules@sap\cds-dk\lib\index.js:1:30)
at Module._compile (node:internal/modules/cjs/loader:1254:14)

Tested with NodeJS versions:

NodeJS Version	result
18.13.0	TypeError: Cannot redefine property: _log
18.15.0	TypeError: Cannot redefine property: _log
18.16.1	TypeError: Cannot redefine property: _log
16.16.0	working - no error

Steps to reproduce

1. Use NodeJS 18.16.1

2. init project

   cds init
   npm install --save-dev cds-swagger-ui-express
   

3. Add server.js

   const cds = require ('@sap/cds')
   module.exports = cds.server
   
   if (process.env.NODE_ENV !== 'production') {
     const cds_swagger = require ('cds-swagger-ui-express')
     cds.on ('bootstrap', app => app.use (cds_swagger()) )
   }
   ```

4. start app with cds run or cds watch (cds watch gives a stacktrace)

Best Regards

Support OData flavors different than the default one of CAP

Let's assume I have the following entities in my CAP project and expose them directly via an OData service:

using {managed} from '@sap/cds/common';

entity Authors {
  key name: String(64);
      age: Integer;
      [...]
      reviews: Association to many Reviews on reviews.reviewee = $self;
}

entity Reviews : managed {
  key uuid: UUID
      reviewee: Association to Authors;
      rating: Integer;
  [...]
}

I specify the desired OData flavor explicitly in my .cdsrc.json file like this:

{
  "odata": {
    "flavor": "x4"
  }
}

Now, if I do a GET .../Reviews('43cf695f-4a13-4666-1240-d473f40fb23b') I would receive a response object like this one:

{
  "uuid": "43cf695f-4a13-4666-1240-d473f40fb23b",
  "reviewee": {
    "name": "John Doe"
  },
  "rating": 5
}

The cds-swagger-ui-express library instead generates a swagger UI with a response object like this:

{
  "uuid": "43cf695f-4a13-4666-1240-d473f40fb23b",
  "reviewee": "John Doe",
  "rating": 5
}

I guess the library cannot handle the custom OData flavor correctly in this case.

Value of 'namespaceAndName' parameter must be in the following format: <namespace>.<name>

Hi,

the error message comes from the cds runtime. But it is caused by the cds-swagger-ui-express plugin.

Steps to reproduce:

1. Create a basic CAP App (DB + Service + server.js with this plugin)
2. Define some annotation including the $type definition
3. Start the server
4. Call the swagger-UI an execute a simple get (on an entity with a annotation as described in step2)

The server will raise the given error.
If you would call the GET of the entity first and after that the via swagger UI. The error does not happen.

It took me some time to find out, that this plugin is causing the issue and therefore I already has done some analysis of the potential root cause.
I'm relativ new to CAP/JS so it might be I'm miles off, but still I wanted to share the Information.

The issue can be reproduced without the plugin adding the following lines to server.js:
const cds_dk = require('@sap/cds-dk')
cds.on('serving', service => {
cds_dk.compile.to.openapi(service.model, {
service: service.name
})
})

This call is happening when calling the swagger UI.
And somehow the compile is filling the annotation buffer for the service of CDS with wrong/bad data.

Because normally the $type annotation would not be present and therefore $type would never be checked.
But wenn calling the compile before any normal request happens the "full" annotations for the serve are loaded into the CDS annotation model and not all annotation will have the wanted schema.

Case this is an error maybe on the plugin side oder maybe on sap/cds side I also have an ongoing oss-support ticket.

An "basic workaround" would be to simply create a basic fetch to get the entity (this will fill the service annotation buffer on the CDS side).
And then call the compile. With this setup the error magically disappears.

I hope the description is somehow clear an can help to improve the plugin (with I really like a loot! -thanks for all the time you have save me!)

regards
Norbert

PS: If it would help I could provide a zip with an example setup.

Error: Cannot find module 'cds-swagger-ui-express'

Deploy cds-swagger-ui-express to production, it still appears the error: Error: Cannot find module 'cds-swagger-ui-express'.
Environment:

"dependencies": {
    "@sap/cds": "^7",
    "@sap/cds-hana": "^2",
    "@sap/xssec": "^3",
    "express": "^4",
    "passport": "^0",
    "cds-swagger-ui-express": "^0.8.0"
  },
  "devDependencies": {
    "@cap-js/sqlite": "^1",
    "@sap/cds-dk": "^7",
    "cds-swagger-ui-express": "^0.8.0"
  }

swagger-ui-init.js serving wrong content if you have multiple services

if you have multiple services like

• servicePathA
• servicePathB
• servicePathC

and you are calling the api-docs from servicePath A
then the api-docs from servicePath B
and then swagger-ui-init.js from servicePathA
and then swagger-ui-init.js from servicePathC
you will see wrong content in file swagger-ui-init.js .

This as well happens if your swagger ui service runs with multiple replicas in the cloud and the router dispatches randomly to the service replica instances.

The issue can be solved by using serveFiles instead of serve

app.use('/api-docs-one', swaggerUi.serveFiles(swaggerDocumentOne, options), swaggerUi.setup(swaggerDocumentOne));
app.use('/api-docs-two', swaggerUi.serveFiles(swaggerDocumentTwo, options), swaggerUi.setup(swaggerDocumentTwo));

see docu of
https://www.npmjs.com/package/swagger-ui-express
--> Two swagger documents

How to enable "Authorize" or pass Bearer token for xsuaa backed CDS services?

Hello,

For secured CDS services, is there a way to enable Authorization as available in Swagger UI? For example to pass Auth Bearer token?

How can the same be enabled for this package?

Many thanks!

Hide empty entities in SwaggerUI

Hello,

Is there an option to hide empty entities and only show those entities, where HTTP-Operations are available?

Best Regards

Boolean parameter not working in "Try It Out" mode

I found this issue when doing the following -

• Set up basic CAP application using wizards.
• Enable drafts as in this setting - Enable Drafts
• Compile swagger file using default command - "cds compile srv --service all -o docs --to openapi"

The drafts APIs all include a parameter called "IsActiveEntity" which is a boolean parameter. It seems to look correct in the json file, but the "Try It Out" feature in the swagger page doesn't work because it seems to wrap the parameter value in quotes, instead of directly passing it in. Not sure if this breaks down here or somewhere in the swagger dist itself.

CVE-2022-31129

Hi Christian,

Any chance to update the version of @sap/cds-dk in this library?
Whitesource is failing because of vulnerable moment-2.29.3 lib.

thanks,
Jonatan

Adding requests for mediatype

Currently it is not possible to retrieve / upload CAP defined mediatypes in the generated swagger ui. This would be a useful feature.

Wrong return of PATCH request

SAP CAP returns the entity with status 200 on a Patch request of that entity.

Generated swagger states the the return code is 204 and body is empty.