OpenAPIs in the SAP ecosystem

ajmaradiaga · ‎10-10-2022

In this blog post, I will cover what the OpenAPI specification is, how different SAP products have adopted OpenAPI specification, how you can get started, which tools you can use, and how you can document your existing APIs without much effort.

OpenAPI Initiative

What is an OpenAPI specification (OAS)?

From the OpenAPI specification, Introduction section - https://spec.openapis.org/oas/latest.html#introduction...

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

In simple terms, the specification is a document that describes an API.

The OpenAPI specification was donated to the Linux Foundation under the OpenAPI Initiative back in 2015. Before this, it was known as Swagger specification. You might bump into some websites/documentation that still refers to the specification as Swagger or use Swagger and OpenAPI spec interchangeably. The proper name is OpenAPI, not Swagger or Open API, and it is how I will refer to it in this blog post.

Swagger is a collection of tools for API development created by SmartBear Software. One of its most popular tools, and one that you've probably seen around, is Swagger UI. Swagger UI is commonly embedded in products, to allow developers to test the APIs that they publish. You can see a Swagger UI in the SAP Ariba Developer Portal or in the API Business Hub Enterprise. Unfortunately, people commonly refer to Swagger UI as just Swagger which can be confusing at times.

Swagger UI in SAP Ariba Developer Portal

Why is it important?

The OpenAPI specification is an industry standard, it is widely adopted by different vendors/services to document their APIs and there is a large community behind it.

SAP has adopted the OpenAPI spec to document its APIs, e.g. in the SAP API Business Hub you can find the OpenAPI spec for the APIs exposed by the different products. Also, you can use (create/import) OpenAPI specification in different products e.g. SAP Process Automation, API Management, Cloud Integration, SAP Data Intelligence, and use the OpenAPI spec to define/consume/manage APIs.

What does an OpenAPI spec look like?

The OpenAPI spec can be in JSON or YAML format. To get familiar with the content of an OpenAPI spec document, let's look at the OpenAPI spec of an API available in the API Business Hub. If you download the JSON file listed within a product API, e.g. SAP S/4HANA Cloud - Business Partner API (A2X) (API resources > API specification > JSON), and inspect it. You'll notice a structure like the one in the screenshots below.

In the OpenAPI spec, there are only 3 required sections - openapi, info, and paths:

openapi: We can see that the spec below follows the OpenAPI spec version 3.0.0.

info: Includes some metadata of the API.

paths: This sections tells us all the available paths and operations (GET, PUT, POST, DELETE, etc.) for the API.

Specification extensions: All the x- fields, e.g. x-sap-api-type, x-sap-shortText, x-sap-api-deprecated, that are included in the image above are extension fields. In this case, they are there to document additional information for the different types of APIs that SAP products expose. The SAP API Business Hub process these specification extensions to better reflect the APIs in the UI.

All other sections in the spec, e.g. components, externalDocs, security, servers, tags are optional. In the screenshots, we can see that these have been specified for the API but they might not be included, e.g. if there is no server information or no security in the API. Let's explore these optional sections:

components: Contains the schemas of the different data structures expected by our API. Defining this can help developers understand the different objects and their structures.

externalDocs: Additional external documentation.

security: Security mechanism supported by the API, e.g. Basic authentication, OAuth 2.0.

servers: Connectivity information for the server(s) where the API is available.

tags: Additional metadata can be provided in this section.

OpenAPI specification document - paths

Now that we have a brief understanding of the OpenAPI spec, let's have a look at how it has been adopted in different SAP products.

OpenAPI specification adoption in different SAP products

Cloud Application Programming model (CAP):
- Generate an OpenAPI spec for a service: You can convert CDS models to the OpenAPI specification.
```
$ cds compile srv --service all -o docs --to openapi
```
- Import an OpenAPI spec as an external service: This is a feature introduced in the June 2022 release of CAP. wittro goes into the details on how to do this in his Import OpenAPI-documented APIs remotely with SAP Cloud Application Programming Model blog post.
```
$ cds import ~/Downloads/MyOpenAPI-spec.json
```
- Include Swagger UI as part of the CAP service: Embedded in Node.js
```
$ npm add --save-dev cds-swagger-ui-express
```

SAP Cloud SDK: Generate an OpenAPI client using openapi-generator. It's a command line tool (CLI) capable of converting any OpenAPI specification into a TypeScript or JavaScript type-safe client library. Check out ksivakumar blog post - How to use the OpenAPI client Generator of SAP Cloud SDK - to learn how to use it.
```
$ npm install -g @sap-cloud-sdk/openapi-generator

$ openapi-generator --input <input> --outputDir <outputDirectory>
```

SAP Data Intelligence: Has two operators, OpenAPI Client and OpenClient Server, which can interact with an OpenAPI specification document. Note: The OpenAPI specification document is not required, as you can communicate with plain APIs/serve plain APIs using the operators.
- OpenAPI Client: You can generate a custom operator and a demo graph using the generateOpenAPIClient REST operation of the engine.
- OpenAPI Server: If the Swagger specification parameter is specified, a GET request to /openapi/service/_basePath_/swagger.json will return the OpenAPI spec document.

SAP Process Automation: You can call external services from SAP Process Automation by using the Actions Project. To create an Actions Project, you need to import an OpenAPI specification file. The Actions editor functionality was recently added to the Actions project in SAP Process Automation, check out this Devtoberfest session - https://youtu.be/HU7Lir3AQbY?t=477 - with archana.shukla to learn more about the Actions editor functionality
⚠️ There are some limitations on calling actions from processes.

SAP API Business Hub: On SAP API Business Hub, you can find SAP and partner APIs. All public APIs exposed by SAP products are available in the API Business Hub and you can find/download the OpenAPI specification for each in the API resources > API specification area as mentioned in the What does an OpenAPI spec look like section above. Also, you will be able to test the APIs available against a sandbox and live environments. The easiest way to find the APIs you are interested in is by using the search and filter functionality available.

SAP Integration Suite:
- Cloud Integration: You can define a source/target message in Cloud Integration by importing an OpenAPI spec JSON file. There are some limitations on message structures that are not supported when using an OpenAPI spec.
  - Use schema of data structure in mapping: deepakgovardhanrao.deshpande goes into the details on how to use Swagger/OpenAPI Spec JSON in Message Mapping in his blog post.
  💡 You can generate an OpenAPI specification document for the integration flows that you expose via HTTP. By doing this you can document the payloads expected by the integration flow. Also, you can use it in API Management to expose the integration flow.
- API Management: API Management is THE product SAP offers to build, design, publish, analyse, consume, monetise your APIs. API Management supports the creation and import of API definitions in OAS 2.0 and OAS 3.0 versions.
  - Create an API from API Designer: You can create APIs in API designer. The API designer uses the OpenAPI spec to define the APIs.
  - Export an API: You can export an API from API Management. When using the export functionality you will download a .zip file. The zip file contains within the Documentation folder the OpenAPI specification document of the API, e.g. SWAGGER_JSON_en.html. Note: Although the extension of the file is .html, the actual content is a JSON file. I know, misleading.
  - Import an OpenAPI spec: If you've defined the OpenAPI spec externally, you can import the file to create an API in API Management.

OpenAPI community/tools

It is possible that by now you might be wondering how you can get started, which tools you can use, or how you can document your existing APIs without much effort. I have some great news for you.... as mentioned in the Why is it important section, there is a large community behind the OpenAPI Initiative. In this section, I will highlight some of the tools that I've used and some that might come in handy when creating your APIs.

The team behind APIs you won't hate has compiled a list of OpenAPI tools. Check it out as it is likely that there's already a tool out there that can ease your adoption of OpenAPI specifications.

OpenAPI.tools - Converters

json_typegen: Generate a JSON schema from a JSON payload.

$ json_typegen ~/Downloads/input.json --output-mode json_schema 

{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Generated schema for Root", "type": "object", "properties": { "definitionId": { "type": "string" }, "context": { "type": "object", "properties": { "show_id": { "type": "string" }, "show_name": { "type": "string" }, "number_of_attendees": { "type": "number" } }, "required": [ "show_id", "show_name", "number_of_attendees" ] } }, "required": [ "definitionId", "context" ] }

JSON schema to OpenAPI schema: Convert a JSON schema to an OpenAPI schema. Important to embed object schemas in components. Version 3.1 of the OpenAPI specification will support referencing JSON schemas.
```
$ json-schema-to-openapi-schema convert output.json
```

OData to OpenAPI: You can convert the EDMX of your OData services to an OpenAPI format. martin-pankraz shows us in his blog post - Open your SAP OData APIs for some swagger - how you can use the converter. If you prefer using the command line, here you go:
```
$ npm install -g odata-openapi 



# EDMX from the SAP S/4HANA Cloud Bank API - https://api.sap.com/api/BANK_0002/overview 

$ odata-openapi3 BANK_0002.edmx BANK_0002.openapi3.json
```

OpenAPI extension for Visual Studio Code: It includes Swagger UI, IntelliSense, linting, schema enforcement, code navigation, definition links, and snippets... Very handy when navigating large OpenAPI specification documents.

postman-to-openapi: You can convert Postman Collection v2.1/v2.0 to OpenAPI v3.0. Extremely useful if you've created a Postman collection for an API that you interact with frequently.
```
$ npm install -g postman-to-openapi

$ p2o SAPProcessAutomation.postman_collection.json -f SAPProcessAutomation.yml
```

Swagger UI: Visualise and interact with any documented API that follows the OpenAPI specification. You can easily run a client and visualise an OpenAPI spec using Docker.
```
$ docker run -p 8080:8080 \

             -e SWAGGER_JSON=/foo/API_BUSINESS_PARTNER.json \

             -v ~/Downloads:/foo \

             swaggerapi/swagger-ui
```
ABAP OpenAPI UI v2: 8d8214c7f9734f45be69f95cc0d5aeee shows us in his blog post how you can integrate Swagger UI in SAP NetWeaver Gateway.

yq: A lightweight and portable command-line YAML, JSON and XML processor. Not strictly related to OpenAPI but some tools will only allow you to interact/import an OpenAPI specification document in JSON format, so you might need to convert it.
```
# p2o outputs a YAML file, you can convert it using yq

$ p2o SAPProcessAutomation.postman_collection.json | yq -o json > SAPProcessAutomation-OpenAPI.json
```

Thanks for making it this far. I hope you find this blog post useful and that you now have a brief understanding of how you can get started with the OpenAPI specification and the different SAP products that use it in some shape or form. Please share in the comments section any tools that you use when creating OpenAPI specification documents so that others can benefit from them.