Search

    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
    

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

    openapi

    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
    

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

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

    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

    Term Annotation Target OpenAPI field
    Computed Property omit from Create and Update structures
    DefaultNamespace Schema path templates for actions and functions without namespace prefix
    Description Action, ActionImport, Function, FunctionImport summary of Operation Object
    Description EntitySet, Singleton description of Tag Object
    Description EntityType description of Request Body Object
    Description ComplexType, EntityType, EnumerationType, Parameter, Property, TypeDefinition description of Schema Object
    Description Schema, EntityContainer info.title
    Example Property example of Schema Object
    Immutable Property omit from Update structure
    LongDescription Action, ActionImport, Function, FunctionImport description of Operation Object
    LongDescription Schema, EntityContainer info.description
    Permissions:Read Property omit read-only properties from Create and Update structures
    SchemaVersion Schema info.version

    Capabilities

    Term Annotation Target OpenAPI field
    CountRestrictions
    /Countable
    EntitySet $count system query option for GET operation
    DeleteRestrictions
    /Deletable
    EntitySet, Singleton DELETE operation for deleting an existing entity
    /Description EntitySet, Singleton summary of Operation Object
    /LongDescription EntitySet, Singleton description of Operation Object
    ExpandRestrictions
    /Expandable
    EntitySet, Singleton $expand system query option for GET operations
    FilterRestrictions
    /Filterable
    EntitySet $filter system query option for GET operation
    /RequiredProperties EntitySet required properties in $filter system query option for GET operation (parameter description only)
    /RequiresFilter EntitySet $filter system query option for GET operation is required
    IndexableByKey EntitySet GET, PATCH, and DELETE operations for a single entity within an entity set
    InsertRestrictions
    /Insertable
    EntitySet POST operation for inserting a new entity
    /Description EntitySet summary of Operation Object
    /LongDescription EntitySet description of Operation Object
    KeyAsSegmentSupported EntityContainer paths URL templates use key-as-segment style instead of parenthesis style
    NavigationRestrictions
    /RestrictedProperties
    EntitySet, Singleton operations via a navigation path
      /DeleteRestrictions/... EntitySet, Singleton DELETE operation for deleting a contained entity via a navigation path
      /FilterRestrictions/... EntitySet, Singleton $filter system query option for reading related entities via a navigation path
      /InsertRestrictions/... EntitySet, Singleton POST operation for inserting a new related entity via a navigation path
      /ReadByKeyRestrictions/... EntitySet, Singleton GET operation for reading a contained entity by key via a navigation path
      /ReadRestrictions/... EntitySet, Singleton GET operation for reading related entities via a navigation path
      /SearchRestrictions/... EntitySet, Singleton $search system query option for reading related entities via a navigation path
      /SelectSupport/... EntitySet, Singleton $select system query option for reading related entities via a navigation path
      /SkipSupported EntitySet, Singleton $skip system query option for reading contained entities via a navigation path
      /SortRestrictions/... EntitySet, Singleton $orderby system query option for reading related entities via a navigation path
      /TopSupported EntitySet, Singleton $top system query option for reading contained entities via a navigation path
      /UpdateRestrictions/... EntitySet, Singleton PATCH operation for modifying a contained entity via a navigation path
    ReadByKeyRestrictions
    /Readable
    EntitySet GET operation for reading a single entity by key
    /Description EntitySet summary of Operation Object
    /LongDescription EntitySet description of Operation Object
    ReadRestrictions
    /Readable
    EntitySet, Singleton GET operation for reading an entity set or singleton
    /Description EntitySet, Singleton summary of Operation Object
    /LongDescription EntitySet, Singleton description of Operation Object
    SearchRestrictions
    /Searchable
    EntitySet $search system query option for GET operation
    SelectSupport
    /Supported
    EntitySet, Singleton $select system query option for GET operation
    SkipSupported EntitySet $skip system query option for GET operation
    SortRestrictions
    /NonSortableProperties
    EntitySet properties not listed in $orderby system query option for GET operation
    /Sortable EntitySet $orderby system query option for GET operation
    TopSupported EntitySet $top system query option for GET operation
    UpdateRestrictions
    /Updatable
    EntitySet, Singleton PATCH operation for modifying an existing entity
    /Description EntitySet, Singleton summary of Operation Object
    /LongDescription EntitySet, Singleton description of Operation Object

    Validation

    Term Annotation Target OpenAPI field
    AllowedValues Property enum of Schema Object - list of allowed (string) values
    Exclusive Property exclusiveMinimum/exclusiveMaximum of Schema Object
    Maximum Property maximum of Schema Object
    Minimum Property minimum of Schema Object
    Pattern Property pattern of Schema Object

    Authorization

    Term Annotation Target OpenAPI field
    Authorizations EntityContainer securitySchemes of Components Object / securityDefinitions of Swagger Object
    SecuritySchemes EntityContainer security of OpenAPI / Swagger Object

    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
    }
    

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

    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
        }
    }
    
    Show/Hide Beta Features