Publishing to OpenAPI ​

You can convert CDS models to the OpenAPI Specification, a widely adopted API description standard.

Usage from CLI ​

For example, this is how you convert all services in srv/ and store the API files in the docs/ folder:

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

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

With the --openapi:diagram parameter, you can also include a yuml ER diagram of the service entities in the Open API file.

The default value of the server URL is the service base path as declared in the CDS source.

If you have a single server and you want to set the server URL, use --openapi:url <Server URL for Open API export> option. Include the service path in the URL. For that, you can use the ${service-path} variable.

If you want to configure multiple servers, you can use --openapi:servers <JSON_Object_defining_servers> which accepts stringified JSON of the server object. Here, you can pass multiple server objects by passing the stringified JSON objects as an array.

cds compile srv service.cds --to openapi --openapi:servers "\"'[{\\\"url\\\":\\\"api.sandbox.com\\\",\\\"description\\\":\\\"Test URL\\\"},{\\\"url\\\":\\\"api.prod.com\\\",\\\"description\\\":\\\"Production URL\\\"}]'\""

cds compile srv service.cds --to openapi --openapi:servers "\"'[{\\\"url\\\":\\\"api.sandbox.com\\\",\\\"description\\\":\\\"Test URL\\\"},{\\\"url\\\":\\\"api.prod.com\\\",\\\"description\\\":\\\"Production URL\\\"}]'\""

Note: --openapi:url is ignored when this option is specified.

Swagger UI ​

Embedded in Node.js ​

In Node.js apps, the standard Swagger UI can be served with the help of the cds-swagger-ui-express package:

npm add --save-dev cds-swagger-ui-express

npm add --save-dev cds-swagger-ui-express

You need a server.js file to integrate it in the bootstrap process:

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()) )
}

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()) )
}

Swagger UI is then served at $api-docs/.... Just follow the Open API preview links on the index page:

Learn more about the cds-swagger-ui-express.

Embedded in Java ​

Swagger UI is not available out of the box for CAP Java. However, check out this commit in our CAP Java sample application that demonstrates how to integrate a Swagger UI into your Spring Boot application.

Online Swagger Editor ​

Alternatively, you can use the online Swagger editor with the OpenAPI files produced with the CLI. In this case, you likely need to enable CORS because the swagger.io site needs to call localhost. You can use the cors middleware, for example.

Annotations ​

The OData to OpenAPI Mapping can be fine-tuned via annotations in the CSDL ($metadata) documents.

See Frequently Asked Questions for examples on how to use these annotations.

Core Annotations ​

Capabilities ​

Validation ​

Authorization ​

Frequently Asked Questions ​

Examples for typical questions on how to fine-tune the generated OpenAPI descriptions.

How do I suppress GET (list and by-key) on an entity set? ​

To suppress both types of GET requests to an entity set, annotate it with

"@Capabilities.ReadRestrictions": {
    "Readable": false
}

"@Capabilities.ReadRestrictions": {
    "Readable": false
}

How do I suppress GET (list) on an entity set? ​

To suppress only GET list requests to an entity set and still allow GET by-key, annotate it with

"@Capabilities.ReadRestrictions": {
    "Readable": false,
    "ReadByKeyRestrictions": {
        "Readable": true
    }
}

"@Capabilities.ReadRestrictions": {
    "Readable": false,
    "ReadByKeyRestrictions": {
        "Readable": true
    }
}

How do I suppress GET (by-key) on an entity set? ​

To suppress only GET by-key requests to an entity set and still allow GET list, annotate it with

"@Capabilities.ReadRestrictions": {
    "ReadByKeyRestrictions": {
        "Readable": false
    }
}

"@Capabilities.ReadRestrictions": {
    "ReadByKeyRestrictions": {
        "Readable": false
    }
}