onedevatlasBeta
Browse the atlas
AllCAPUI5ABAPBTP
CDS pluginCDS plugintypeInstalls into a CAP project and extends the runtime. CAP loads it through cds.requires or the plugin hook.See every one →What this type is →by SAPby SAPoriginPublished by SAP itself. A visible facet, never an input to a reading — a dormant official plugin reads exactly like a dormant independent one.See every one →

@cap-js/openapi

Turns a CDS service into an OpenAPI document, derived from the model so the description cannot drift from what is served.

GitHub7 ★
npm74,761/wk

Facts

Latestv1.7.0ReleasedLast pushLicenceApache-2.0

Where it sits

Lives in
CAP
Provides
OpenAPICAPOpenAPIcapabilityHanding a description of the service to clients and tools — an API portal, a code generator, a partner who wants a contract before they write anything.
Flavors
Node.js
Requires
@sap/cds≥ 7.6@sap/cdsartifactThe peer range, as published.

Who is behind it

SAP Cloud Application Programming ModelSAP Cloud Application Programming ModelOrganisationMaintains this
In the atlas: maintains 34@cap-jsmaintainerChristian GeorgiPersonContributes to this
In the atlas: maintains 1, contributes to 53@chgeocorporateuserPersonContributes to this
In the atlas: contributes to 3@corporateusercronossclkPersonContributes to this
In the atlas: contributes to 1@cronossclkChristian SchüringsPersonContributes to this
In the atlas: contributes to 25@cschueringsDaniel O'GradyPersonContributes to this
In the atlas: contributes to 10@daogradyGuilherme DellagustinPersonContributes to this
In the atlas: contributes to 27@dellagustin-sapDiptoPersonContributes to this
In the atlas: contributes to 2@Dipto-at-sapGeethika PulaPersonContributes to this
In the atlas: contributes to 2@Geethika-PulaHeiko TheißenPersonContributes to this
In the atlas: contributes to 2@HeikoTheissenIsaac PalomeroPersonContributes to this
In the atlas: contributes to 1@isaacpalomero20 contributors

Before choosing this

Conditions

LicenceSAP Developer License Agreement 3.2 CAP§ 1, 2, 3A cds-plugin is used with SAP CAP materials, or an artifact is explicitly identified as a CAP plugin or application.
  • § 1 License. Productive customer applications are limited to SAP BTP or another SAP-licensed platform, and mass extraction to a non-SAP product is restricted except where solely required for SAP interoperability.
  • § 2 Intellectual Property. The agreement retains SAP's rights in the covered materials and limits making APIs, tools or software available to third parties, while preserving ownership of customer applications subject to SAP's underlying rights.
  • § 3 Artificial Intelligence Training. The agreement prohibits use of the covered materials and customer applications for training artificial-intelligence models or systems.
SAP Developer License Agreement 3.2 CAP →

What it declares

Every artifact

Type
CDS plugin
Origin
By SAP

As a CDS plugin

Declared for
>=7.6
Distributed through
npm

Connections1

Install

npm add @cap-js/openapi

Derived from the package name. No recipe recorded; the README has the configuration.

README

quoted from cap-js/openapi under Apache-2.0, read
cap-js/openapi/README.mdOn GitHub

REUSE status

OpenAPI

About this project

The @cap-js/openapi is a package that provides support for OpenAPI document compilation.

Table of Contents

Requirements and Setup

Installation
$ npm install @cap-js/openapi
Usage
const cds = require('@sap/cds')
const { compile } = require('@cap-js/openapi')
const csn = await cds.load(cds.env.folders.srv)
const openapiDocument = compile(csn)
Customizing OpenAPI Output

You can synchronously hook into the compilation process using the after:compile.to.openapi event to modify the generated OpenAPI document:

cds.on('after:compile.to.openapi', ({ csn, options, result }) => {
  // Add custom vendor extensions
  result['x-api-id'] = 'my-api-id'

  // Enhance the info section
  result.info.contact = {
    name: 'API Support',
    email: 'support@example.com'
  }
  result.info.license = {
    name: 'Apache 2.0',
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
  }

  // Add additional servers for different environments
  result.servers.push({
    url: 'https://api-dev.example.com',
    description: 'Development server'
  })
})

The event handler receives an object with:

  • csn - The input CSN model
  • options - The compilation options used
  • result - The generated OpenAPI document (can be modified by reference)

In the same vein, you can also subscribe to compile.to.openapi, to modify the incoming CSN before it is converted:

cds.on('compile.to.openapi', ({ csn, options }) => {
  // exclude MySecretEntity from output
  delete csn.definitions.MySecretEntity
})

The handler for events should never be async to avoid race conditions between the handler and the conversion process!

Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2023 SAP SE or an SAP affiliate company and contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.

Apache-2.0, read

History

Latest

v1.7.0dated in the atlas

Removed, Deprecated, Security, Features 2, Changed 2, Fixes 6

Notes
Added
  • Added defaultProtocol configuration option as fallback if no config is provided.
  • Collection responses now include the optional @odata.nextLink / @nextLink property in their schema, documenting server-driven paging as per the OData specification.
Changed
  • set odata as the service protocol if no protocol is set to match the default behavior of @sap/cds. Provide cds.env.openapi.defaultProtocol = "rest" to restore old behavior.
  • ER diagrams are now rendered using the yuml.me v1 API (app.yuml.me), avoiding the 'please migrate' image. The diagram and legend are displayed as clickable SVG images.
Deprecated
Removed
Fixed
  • @Common.Label values containing i18n placeholders (e.g. {i18n>TasksPlural}) are no longer corrupted by camelCase word-splitting in tag names
  • Entities that are transitively autoexposed and should still be considered readonly, do not generate documentation for write endpoints anymore
  • Back-reference navigation properties on child entities in compositions (the generated parent nav pointing back up) are no longer emitted in the OpenAPI read schema
  • Implicitly auto-exposed composition targets (annotated @cds.autoexposed by the CDS compiler) no longer generate top-level GET paths that CAP would reject with 405
  • OpenAPI compilation is now pure: the input CSN is no longer mutated during compilation
  • Services annotated with @protocol: 'rest' no longer include a /$batch path in the generated OpenAPI document
Security

  1. v1.6.0

    Removed, Deprecated, Security, Features 1, Changed, Fixes 1

    Notes
    Added
    • Support @Validation.MinItems and @Validation.MaxItems annotations on collection-typed properties and action parameters to emit minItems/maxItems in the generated OpenAPI schema
    Changed
    Deprecated
    Removed
    Fixed
    • @assert.range (and @Validation.Minimum/@Validation.Maximum) on properties and action parameters of type Edm.Int32, Edm.Int16, Edm.SByte, and Edm.Byte now correctly produces minimum/maximum in the generated OpenAPI schema
    Security

  2. v1.5.0

    Removed, Deprecated, Security, Features 1, Changed, Fixes 3

    Notes
    Added
    • Generate media stream paths (GET and PUT) for media entities and Edm.Stream properties
    Changed
    Deprecated
    Removed
    Fixed
    • Restore bound actions/functions on containment navigation paths (regression since v1.2.0)
    • Function parameters annotated with @mandatory no longer lead to "Unexpected mandatory after optional parameter" error
    • GET, PATCH, and DELETE endpoints are now exposed as navigation paths for *_texts entities
    Security

  3. v1.4.2

    Security 1

    Notes
    Security
    • Replaced unauthorized release 1.4.1 — this version is identical to 1.4.0

  4. v1.4.0

    Security, Features 1, Changed 1, Fixes 2

    Notes
    Added
    • Opt-in option shortActionPaths to use simplified bound action paths (e.g., .../Discount instead of .../ODataDemo.Discount). Enable via { "cds": { "openapi": { "shortActionPaths": true } } } in package.json.
    Changed
    • Removed special characters from placeholders for fields like short text, description, etc.
    Fixed
    • Autoexposed .texts entities are now excluded from OpenAPI document
    • Generate navigation paths to CRUD-disabled entities
    Security

  5. v1.3.1

    Security, Fixes 1

    Notes
    Fixed
    • Properties marked with @Capabilities.ExpandRestrictions.NonExpandableProperties are now excluded from OpenAPI schemas
    Security

  6. v1.3.0

    Features 2, Changed 5, Fixes 3

    Notes
    Added
    • Util to regenerate OpenAPI test snapshots
    • Calling cds compile -2 openapi now emits events: compile.to.openapi with an object parameter, containing the source model and the compilation options before the compilation takes place. after:compile.to.openapi carries the same parameter with an additional result property, containing the output of the compilation process.
    Changed
    • Operations: @Core.Description maps to summary, @Core.LongDescription maps to description
    • Parameters and schema properties: use @Core.LongDescription with fallback to @Core.Description
    • Service info: use @Core.LongDescription with fallback to @Core.Description
    • Acronyms in names are now preserved and not split in description fields.
    • Tags now display with spaces instead of underscores, and camelCase tags are automatically converted to space-separated words (e.g., "camelCase" becomes "camel Case").
    Fixed
    • Reading json from project root
    • Correctly handle @Core.Immutable properties in PATCH requests.
    • Actions without parameters now include requestBody with Content-Type: application/json in OpenAPI spec to prevent 415 errors

  7. v1.2.4

    Fixes 1

    Notes
    Fixed
    • Upgraded qs dependency to 6.14.1 to fix security issue (missing check for array bounds)

  8. v1.2.3

    Features 1, Changed 1, Fixes 1

    Notes
    Added
    • Now writes config file path in case of errors.
    Changed
    • Allow array of objects for @protocol annotation
    Fixed
    • Properly consume @Capabilities.UpdateRestrictions.UpdateMethod

  9. v1.2.2

    Fixes 1

    Notes
    Fixed
    • Properties with @mandatory annotation is now added to required array.

  10. v1.2.1

    Changed 1

    Notes
    Changed
    • Replaced console.warn statements with cds.debug logs for warning messages.

  11. v1.2.0

    Features 1, Fixes 2

    Notes
    Added
    • Now supports @EntityRelationship annotations.
    Fixed
    • Parameter aliases conflict with system query options.
    • Fixed action/function invocation on navigation path to align with CAP runtime.

  12. v1.1.2

    Features 1, Fixes 1

    Notes
    Added
    • Now supports odata-v4 protocol in the @protocol allowed values in CDS along with odata and rest.
    Fixed
    • Fixed the filename issue: when there is only one service in the CDL source, the OpenAPI document is now generated with the filename corresponding to the service name rather than the CDL source filename.

  13. v1.1.1

    Fixes 1

    Notes
    Fixed
    • Fixes server URL based on the version provided by --odata-version value.

  14. v1.1.0

    Features 1, Fixes 3

    Notes
    Added
    • Now supports x-sap extensions using @OpenAPI.Extensions annotations in service, entity and function/action level.
    Fixed
    • Fixed allowedValues on all primitive types.
    • Removed duplicates in tags.
    • No longer append protocol and service name information to the server URL incase of openapi:servers option.

  15. v1.0.7

    Features 3, Changed 1, Fixes 3

    Notes
    Fixed
    • Multiple protocols for a service now renders multiple openapi documents.
    • Format and type are now preserved for function parameters.
    • Fixed allowedValues on all primitive types.
    Changed
    • Using @title, @Core.Description and @Core.LongDescription for titles and descriptions for improving the default texts in info object and x-sap-shortText.
    Added
    • OpenAPI documents can now have externalDocs object provided through @OpenAPI.externalDocs annotation in the service level of CDS.
    • OpenAPI documents now throws warning if securitySchemas are not found.
    • Introduced --openapi:config-file option to incorporate all the options for cds compile command in a JSON configuration file, inline options take precedence over those defined in the configuration file.

  16. v1.0.6

    Changed 1, Fixes 3

    Notes
    Fixed
    • Entities annotated with @cds.autoexpose[d] but explicitly exposed in the service are now made read-write.
    • Added a wrapper properties object for primitive return types.
    • Adding protocol and service name information to the server URL incase of openapi:servers option.
    Changed
    • Using @title, @Core.Description and @Core.LongDescription for titles and descriptions for improving the default texts in info object and x-sap-shortText.

  17. v1.0.5

    Changed 1, Fixes 1

    Notes
    Changed
    • UUID type elements are not going to have the property of required.
    Fixed
    • properties with @mandatory annotation is not added to required array.

  18. v1.0.4

    Changed 1

    Notes
    Changed
    • Minor changes

  19. v1.0.3

    Changed 1

    Notes
    Changed
    • Removed registering compile target

  20. v1.0.2

    Fixes 1

    Notes
    Fixed
    • Bug fixes

  21. v1.0.1

    Fixes 1

    Notes
    Fixed
    • Bug fixes

  22. v1.0.0

    Features 1

    Notes
    Added
    • Initial release
On GitHub
29,123downloads per week, npm
Weekly downloads for @cap-js/openapi26 complete calendar weeks from 2026-04-27 to 2026-10-25; the latest total is 29123.27 Apr – 3 May: 168,1724 May – 10 May: 190,40811 May – 17 May: 198,36018 May – 24 May: 203,65025 May – 31 May: 187,8911 Jun – 7 Jun: 164,0158 Jun – 14 Jun: 213,12215 Jun – 21 Jun: 209,47222 Jun – 28 Jun: 198,49429 Jun – 5 Jul: 201,1716 Jul – 12 Jul: 192,62513 Jul – 19 Jul: 196,51520 Jul – 26 Jul: 195,87527 Jul – 2 Aug: 182,0953 Aug – 9 Aug: 185,62810 Aug – 16 Aug: 141,60717 Aug – 23 Aug: 166,69724 Aug – 30 Aug: 173,72731 Aug – 6 Sept: 128,9017 Sept – 13 Sept: 105,94814 Sept – 20 Sept: 123,70321 Sept – 27 Sept: 147,72328 Sept – 4 Oct: 154,0185 Oct – 11 Oct: 134,30312 Oct – 18 Oct: 73,95319 Oct – 25 Oct: 29,123

Others providing1

Compare all 2 on the OpenAPI page →
OpenAPI
  1. cds-swagger-ui-expressSwagger UI for a CAP service's OpenAPI definition

Details

Sources5
npm registrydiscovered herechecked
The discovery passdiscovered herechecked
npm registry, @cap-js/openapiversion, releases, installschecked
github.com/git+https://github.com/cap-js/openapi.gittree, pushes, contributors, CIchecked
README.mdquoted, and what the entry declareschecked

Sources are graph entities: the same page may back several entries, and an unreachable source flags every row that rests on it.

Compatibility and provenance
declared for>=7.6
latestv1.7.0
first release
releases and cadence22, ~61d median
discovered vianpm registry, The discovery pass
first seen in the atlas
ecosystem and domaincap, protocols-and-apis
Flavors1
Node.js
“const cds = require('@sap/cds')” — cap-js/openapi — READMEchecked
Contributors20
Christian GeorgicorporateusercronossclkChristian SchüringsDaniel O'GradyGuilherme DellagustinDiptoGeethika PulaHeiko TheißenIsaac Palomerojeevitha011Jörg Mannmuskansethi1Ralf HandlTimothy GibbonsRoshniNaveenaSsjvansSteffen WaldmannTim Schulze-HartungZongqi Chen

From the repository’s contributor list, .

History in the atlas2
  1. Turns a CDS service into an OpenAPI document, derived from the model so the description cannot drift from what is served.
  2. First seen.
For your agent
Ref
artifact:cap-js-openapi
JSON
/artifacts/cap-js-openapi.json
MCP
Connecting an agent