Part 2 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communication, Collaboration and Governance

[mohit_bansal3]

This is second blog for the mini blogs series highlighting importance of Open API spec framework. In the previous blog we have got insights for the Open API ( Swagger UI) in general, Let's bring our understanding to utilize the concepts in  SAP BTP CAPM application.

CAPM Open API Framework
Part 1 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communi... Agenda : Recognize the Significance of Standardized and Consistent API Documentation for the CAPM Service (This Blog)
Part 2 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communi... Agenda : CAPM Open API Documentation: Implementation and Development Approach
Part 3 – Empowering SAP BTP CAP Services through Open API Spec and Annotations for Effective Communi... Agenda: Let’s take a deep dive with annotations  & elevate CAPM API documentation to the next level.

Important Note:  This blog post is based on the Node JS based build pack for the BTP CAPM Development.

SAP Cloud Application Programming Model(aka SAP CAP) support multiple build packs i.e. Node JS, Java.

Node JS supports out of the Box Open API Spec and API can be easily published to Open API Specification.

Official Documentation for the CAP & CAP Based Open API can be found here.

Before, We directly jump into the CAPM Open API framework, I would like to take a moment to deepen our understanding how the CAPM Framework will understand the Open API Specification.

Core Data Services (CDS) is a versatile modeling language used for both domain models and service definitions.

These CDS Modelling layer are enriched by Annotations. Services metadata has been generated based on the CDS Modeling Layer & Annotations.

"Open API Framework  generates the Rich Open API Framework based on the CDS Data Model and Annotations."

The diagram below provides a helpful visual representation that gives us a clear understanding of the information discussed above.

SAP BTP CDS Data and Service Modelling , Annotations and OpenAPI Spec

A Step-by-Step Guide to Empower CAPM Services with OpenAPI Specification

Start with very Basic Open API Implementation with Minimal configuration

( This copied code snippet is included solely for the convenience of the readers, allowing them to quickly refer to the code mentioned in the discussion. )

Step 1: Dependency Installation 

• The Node module cds-swagger-ui-express offers built-in support for generating OpenAPI specifications with the Node.js Build Pack.


• To incorporate cds-swagger-ui-express functionality into the CAP application, add the dependency to the Package.json file by installing the required dependencies.

// Important Note: 

// Use npm add --save-dev cds-swagger-ui-express for Local BAS Testing without production deployment

npm install cds-swagger-ui-express​

Step2: BootStraping in Server.js

SAP CAP Server.js bootstrapping sets up the server, configures middleware, and enables extensibility. It also handles error management and provides a foundation for developing CAP-based services.

Create a server.js file in the Project root Folder.

const cds = require ('@sap/cds')

module.exports = cds.server



 const cds_swagger = require ('cds-swagger-ui-express')

 cds.on ('bootstrap', app => app.use (cds_swagger()) )

Step 3: Prepare CDS Model

To demonstrate, I have prepared a simple code snippets to keep the below points in mind

• Multiple entities


• Association between entities


• Text Tables

Here is the code snippet from db/data-model.cds that highlights important aspects of the Open API Framework.

namespace openapi.db;



using {

  cuid,

  temporal,

  Currency

} from '@sap/cds/common';



//Type Declaration

type Guid    : String(32);



type AmountT : Decimal(15, 2) @(

  Semantics.amount.CurrencyCode: 'CURRENCY_CODE',

  sap.unit                     : 'CURRENCY_CODE'

);



define type Amount {

  Currency     : Currency;

  GrossAmount : AmountT;

  NetAmount   : AmountT; 

}

entity Businesspartner {

  key BusinesspartnerGuid : Guid;

      BP_Role             : String(2);

      Email               : String(64);

      MobileNumber        : String(14);

      AdressGuid          : Association to Address;

      BP_ID               : String(16);

      ComppanyName        : String(80);

}



entity Address {

  key AdressGuid      : Guid;

      City            : String(64);

      PostalCOde      : String(14);

      Street          : String(64);

      Businesspartner : Association to one Businesspartner

                          on Businesspartner.AdressGuid = $self;

}

entity Product {

  key ProductGuid  : Guid;

      ProductID    : String(28);

      ProductType  : String(2);

      Category     : String(32);

      Description  : localized String(255);

      SupplierGUid : Association to Businesspartner;

      Price        : Amount;

}

entity Purchaseorder : cuid {

  PurchaseOrder        : String(24);

  Businesspartner_Guid : Association to Businesspartner;

  Amount               : Amount;

  Status               : String(1);

  Items                : Composition of many PurchaseOrderItems

                           on Items.PurchaseOrder = $self;

  Note                 : String(255)

}

entity PurchaseOrderItems : cuid {

  PurchaseOrder  : Association to Purchaseorder;

  ItemNumber     : Integer;

  ProductGuid    : Association to Product;

}

Here is the code snippet from srv/cat-service.cds that highlights important aspects of the Open API Framework.

using {openapi.db as openapi} from '../db/data-model';



service CatalogService {

    entity PurchaseOrders     as projection on openapi.Purchaseorder

    entity PurchaseOrderItems as projection on openapi.PurchaseOrderItems;

    entity BusinessPartners   as projection on openapi.Businesspartner;

    entity Addresses          as projection on openapi.Address;

    entity Products           as projection on openapi.Product

}

Local Testing in Business Application Studio

Metadata Along with Open API Preview

Click on Open API Preview to access the ready-to-use Open API documentation."

At the top section, a visually appealing YUML Diagram will be displayed, providing the following information.

• Visual Representation of the API structure.


• Simplified Communication by presenting a clear overview of the API design.


• Enhanced Understanding for complex API specifications more easily.


• Collaborative Design among team members during the API design process.


• Documentation Efficiency: serve as concise documentation that captures essential API details.

Open API Spec: YUML Diagrams Representing Entities , Entity Set , Types and Relationship

End Points Details

API End Points , Query Operations and Testing

Let's   Deploy the the CAPM Service in Cloud Foundry,

Important Note: Make sure start script is added in the Package.json 

"scripts": {

    "start": "cds-serve"

  }"

 

Real Time Technical Requirement :

Tips & Tricks to deploy only for Non Productive Sub Account

Deployment Challenges

 

Restrict the Open API Spec to Development & QA BTP Sub Account and excludes from Production Sub Account.

To demonstrate the process, I will follow the following steps:

• Created a user-defined environment variable named "OpenAPISpecSupport".


• Set the value of the "OpenAPISpecSupport" variable to "true" in the respective Sub Accounts (Development & QA).


• Read this variable during the bootstrapping of the server.js file using "process.env.OpenAPISpecSupport".


• If the value is true, load the Swagger UI.

User Variable for controlling in Dev SubAccount

So As per the requirement,

• Open API Spec supported via Local BAS Testing


• Open API Spec Supported for Development Sub Account Testing

const cds = require('@sap/cds')

module.exports = cds.server



//Just to demo the value in application log

console.log('process.env.OpenAPISpecSupport', process.env.OpenAPISpecSupport);



// Variable defined in User defined enviroment variable

if (process.env.OpenAPISpecSupport =='true' || process.env.NODE_ENV !== 'production') {

  const cds_swagger = require ('cds-swagger-ui-express')

  cds.on ('bootstrap', app => app.use (cds_swagger()) )

}

Application Log showing OpenAPISpecSupport = True for the Devolvement Sub Account.

User defined environment variable captured via console logging for testing

Few Know Issues & Resolutions

Initially I encountered some technical issues. However, I'm pleased to inform you that the official CAPM documentation has been updated to address those issues and provide solutions. You can find the link below to access the updated documentation.

Common issues & their fixes.

Key Takeaways

Here are the simplified versions of the provided statements:

• Generating Powerful Open API Spec:
  Easily generate a robust Open API Spec using the CAPM Node JS build pack, right out of the box.


• Clear Understanding with YUML Diagram:
  The YUML Diagram provides a self-explanatory visual representation, illustrating all relevant entities and their intricate associations.


• Easy Access to API End Points and Queries:  All API End Points & their corresponding Query Information available in glance.


• Efficiently Examine API Response Fields: Easily view the fields in the API response, enabling comprehensive analysis and understanding.


• Convenient Testing via Open API Spec: Testing is also possible from  Open API Spec.


• Restricted Deployment to Development/QA Sub Account:
  Ensure controlled deployment by limiting it to specific Development or QA Sub Accounts, allowing for a secure and organized environment.

Next blog topic: Stay tuned for the next blog post, where we will explore the Open API Spec Capability with various annotations.

Cheers;

Mohit Bansal