Swagger UI with SAP Commerce Cloud
Swagger UI is a valuable tool that empowers development teams to visualize and interact with API’s resources. By using Swagger UI, we can provide comprehensive instructions on how to effectively use and integrate with our solution’s APIs. This includes detailed information about return types, arguments supplemented with illustrative examples and more.
I won’t delve into the details of how Swagger can be used, as there are already excellent tutorials available online for that purpose:
- Swagger Official Documentation
- YouTube Tutorial”
- https://swagger.io/specification/ — OpenAPI
- …and more you can find easily.
Instead, i want to underline how we can easily use Swagger UI in SAP Commerce Cloud, especially when utilizing the OCC (Omni Commerce Connect) extension. Much of the setup is simplified as it is pre-configured by the “commercewebservices” extension.
Commerce Version 2211
It’s important to note that the Spring MVC configuration responsible for generating API documentation is now imported from the swaggerintegration extension as of version 2211. Furthermore, the Swagger annotations have been updated to be compatible with OpenAPI 3.
To enable Swagger UI, we should add the swaggerintegration extension to our localextension and manifest.json for CCv2 which makes it available in our cloud API endpoint: https://api.xxxxxx-xxxxxx1-s1-public.model-t.cc.commerce.ondemand.com/occ/v2/swagger-ui/index.html
Comprehensive Documentation
In SAP Commerce Cloud documentation, we can find valuable information on how to enable/disable Swagger UI, configure OAuth2 and other essential details: SAP Commerce Cloud Documentation.
For previous versions of SAP Commerce Cloud, we can find details about custom Swagger annotations such as @ApiFieldsParam, @ApiBaseSiteIdUserIdAndCartIdParam, @ApiBaseSiteIdParam, and @ApiBaseSiteIdAndUserIdParam in the documentation. These custom annotations enhance the Swagger documentation for our APIs.
For more information, please refer to the SAP Commerce documentation.
As developers, it’s crucial to adhere to best practices and document our APIs with a user perspective in mind. This approach facilitates better API exploration and interaction, ultimately enhancing the overall development process.
Here’s example link to access Swagger UI in SAP Commerce Cloud instance: https://spartacus-demo.eastus.cloudapp.azure.com:8443/occ/v2/swagger-ui/index.html
