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

[mohit_bansal3]

This mini blog series will encompass the important aspects of API Documentation and its significance in SAP BTP Application development using the Cloud Application Programming (CAPM) framework.

Important Note:

I would like to emphasize that, CAPM application development perspective Open API Specification implementation is technically simple and straightforward. However, it holds immense importance in ensuring the maintenance of a strong governance model, adherence to best practices, and standardization in CAPM based API / Microservices based development.

It will facilitate enhanced collaboration among multiple personas involved.

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.

Recognize the Significance of Standardized and Consistent API Documentation for the CAPM Service (This Blog)

Before proceeding with publishing CAPM services to Open API documentation, It is important to gain a clear understanding of the Open API concept.

What does the Open API concept involve exactly?

Open API Framework  The Open API Specification is a standardized language for defining HTTP APIs, A standardized approach to explain the specification of your API to other people.

• This specification helps to build client code and learn how an API functions to facilitate effective API development.


• Consider the advantages of comprehending the entire API lifecycle and successfully interacting with developer communities both inside and outside of your company.


• Discover more about how control over your APIs and improved collaboration and communication are made possible by the Open API Specification.

Below picture will provide clarity, What I just mentioned above.

"Multiple Persona  > Challenges to Collaborate >  Do API Documentation"

"Let the API Documentation be the Voice of the API Developer, fostering collaboration among diverse stakeholders / Personas."

Persona Involved, Challenges , Benefits of API Documentation

Let's explore the Open API Framework through the Analogy of SAP Business Accelerator Hub(SAP API Hub) : SAP has embraced the OpenAPI specification to articulate the documentation of its APIs. For instance, within the SAP API Business Hub, we can readily access the OpenAPI specification that outlines the APIs offered by various SAP products.

Use case : For example, let's consider the scenario where we need to locate the SAP BTP core services APIs that facilitates tasks such as managing accounts and service entitlements etc.

To navigate in the SAP API Hub, follow these steps:

1. Select the desired Product Line, for example, BTP.
2. Once selected, you will be presented with a list of API Packages specific to the chosen product line.
3. Locate the BTP Core Services within the list.
4. From there, navigate to the BTP Account Service.

( Path Product Line ( Say BTP)  >  API Packages from BTP API >  Find BTP Core Services  > Navigate to Account Service )

Explore OpenAPI Spec with SAP Business Accelerator Hub(SAP API Hub) Let's deep dive above diagram with each highlighted section
Section 1 (Leftmost Section): OpenAPI Specification in JSON or YAML Format The OpenAPI Specification supports both JSON and YAML formats. This information is utilized to generate the OpenAPI specification for the corresponding API.
Section 2 (Middle Section): Understanding the Open API JSON Specification To gain a comprehensive understanding of the Open API JSON Specification, please follow the steps outlined below: 1. Copy the JSON file and paste it into a JSON viewer tool for detailed analysis and examination. Within the JSON file, you will find the following Mandatory Fields: OpenAPI: This field specifies the version of the Open API Specification being used. Info: This field contains a description or title that provides insights into the API. Path: This field offers information regarding API endpoints, query parameters, and query operations. Additionally, the JSON file encompasses the following Optional fields: Components: This field covers optional components associated with the API. ExternalDocs: This field provides references to external documentation related to the API. Security: This field deals with security-related configurations for the API. Servers: This field defines the servers associated with the API. Tags: This field allows for the categorization and organization of API operations using tags. By comprehending these elements within the Open API JSON Specification, you can effectively navigate and utilize its capabilities.
Section 3 (Right Upper Section): Endpoint Details The OpenAPI framework utilizes the provided JSON or YAML file as input and generates comprehensive API documentation. This documentation includes detailed information about all the API endpoints.
Section 4 (Bottom Right Section): Details about specific query parameters and query operations for the endpoint, along with the ability to test the API."

Further Insights Before Diving into the CAPM-Specific Open API Specification

Open API Specification is generic standardized way of representing API document.

for a quick experimental way of our understanding, Let's import the JSON file from the above API Hub ( the one which we have discussed before) and import it into  Swagger Editor(Open API Spec Editor) screen shot below.

It will represent very much similar response that we had explored it via SAP API Hub API Documentation ( section 3 & section 4) above.

• The OpenAPI Specification is a standardized and generic approach for representing API documentation.


• For a quick and experimental way to enhance our understanding, we can import the JSON file from the mentioned API Hub into the Swagger Editor(OpenAPI editor).


• By importing the JSON file into the Swagger Editor, we will be able to visualize a response that closely resembles what we had previously explored through the SAP API Hub API Documentation.


• Specifically, the response in the Swagger Editor will provide a similar representation as the sections 3 and 4 of the SAP API Hub API Documentation.

https://editor.swagger.io/

Import JSON file to Online Swagger Editor

Key Takeaways

• API Documentation holds significant importance in the API governance model.


• Understand the process of generating API Documentation in SAP API Hub.


• Components involved in the Open API Framework.


• The Swagger Editor relies on the Open API file for its functionality.


• The framework used is generic and standardized, applicable for generating responses for CAPM-based APIs (Microservices).

Further Readings / References

1. SAP CAP official Documentation https://cap.cloud.sap/docs/advanced/openapi


2. Adding Swagger UI to CAPM Node Js application by thomas.jung  https://blogs.sap.com/2020/01/23/adding-a-swagger-ui-to-your-sap-cloud-application-programming-model...

Next blog topic: Stay tuned for the next blog post, where we will explore the generation of Open API Documentation for the CAPM Service in greater detail.

Cheers;

Mohit Bansal