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: '[email protected]'
}
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 modeloptions- The compilation options usedresult- 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.