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.
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.
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.
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
:
3.0.0
.
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:
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.
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
$ 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>
💡 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.
.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.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.
$ 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 output.json
$ 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
$ npm install -g postman-to-openapi
$ p2o SAPProcessAutomation.postman_collection.json -f SAPProcessAutomation.yml
$ 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.
# 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.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
User | Count |
---|---|
24 | |
8 | |
7 | |
7 | |
6 | |
6 | |
6 | |
6 | |
6 | |
6 |