OpenAPI

About this project

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

Table of Contents

• OpenAPI
  • About this project
    • Table of Contents
  • Requirements and Setup
    • Installation
    • Usage
      • Customizing OpenAPI Output
  • Contributing
  • Code of Conduct
  • Licensing

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