Technical Articles
10-Steps to Auto – Generate API Documentation from Swagger Inspector for Rest API(S) from SAP CPI
Background
“Consumer friendly API Documentation is the key for successfull implementation of API First Strategy as it directly impacts the wider adoption and consumption of API(S) across external and internal suppliers and partners.”
While swagger or SAP API designer provides a beautiful way to document API(S) for API consumers via RAML/YAML, it is a manual job for API providers generally to build the API definition i.e RAML in the editors from the scratch especially when the request/response structures are complex i.e SAP Objects or when API(S) are built and handed over to support team without any documentation.
The following tutorial will provide a mechanism on how to auto-generate API documentation using Swagger Inspector for rest API(S) exposed in SAP CPI or SAP PO or API definition in SAP API management instead of manually typing the RAML to create API definition. Please use CORS Chrome Extension if you face CORS issue when sending messages to CPI via Swagger Inspector.
Tutorial
Step1: Create a small CPI package AutoGenerateSwaggerForAPI with a content modifier step that accepts the request and sends the JSON response.
Step 2: Open https://inspector.swagger.io/builder on browser
Step 3: Test CPI Endpoint https://CPITenant-iflmap.hcisbp.eu1.hana.ondemand.com/http/SuccessFactors/EmployeeRequest by passing the required required body and username/password in authorization header.
Step 4: Test CPI Endpoint https://CPITenant-iflmap.hcisbp.eu1.hana.ondemand.com/http/SuccessFactors/EmployeeResponse by passing the required response body and username/password in authorization header.
Step 5: Create API Definition by selecting both the Employee request / response and pressing “Create API Definition”
Step 6: Create Swagger User and sign up
Step 7: Go to Swagger hub and press import open API definition From inspector as shown below:
Step 8: Swagger API Definition for Employee Request/Response should be generated and screen should look like this.
Step 9: You can check request schema and response schema as shown below:
Step 10: You can Download Swagger/OpenAPI JSON as shown below:
Hi Sravaya - Thanks for sharing this.
Could you please shed some light on how to use this open API
where/how this can be used? Can we link to the API's generated under API Management similar to
the Business Hub APIs provided by SAP?
Sorry, I am trying to understand the exact use case of this functionality.
Thanks
Rajesh Pasupula
The usecase is right in background section, it auto generates yaml/ open api definition for any API based on json structure, you don’t need to create open api definitions from scratch in API designer editor manually which will consume so much time when your API has complex structure. Check out blog on swagger inspector in the background section for more detail.
Hi Sravya,
I have tried it but is not documenting the response.
Any clue?
Regards
I know I'm 2 years late to respond 😛
But the answer to your query is to add a content modifier and explicitly mention the header : content-type - application/json before end message in iFlow. This should solve the missing response issue.