This article explains how to use the swagger/Open API specifications for the Petstore API provided by swagger.io both with OAS V2 and V3 in IBM API Connect. This is a point in time statement. The behavior of IBM API Connect may change in the future and simplifies the use of those APIs.
I have updated this article recently (26th April 2023) to use both APIC Connect versions 10.0.1.9 and 10.0.5.2. So I reorganised it a little. Since the API Connect user interface does not change, I do not take screen captures for both versions, but only with 10.0.5.2 and will indicate if they are differences.
The use of the petstore sample provided by Swagger.io has been used quite a lot in the past. It needs to be updated to work without any issues in API Connect. The security configuration for OAuth requires a configuration that does not exist by default for example.
The two Swaggers based respectively on 1.0.6 (OAS2) and 1.0.9 (OAS3) can be found below.
Version | Documentation | Link to specification document | Corrected |
---|---|---|---|
1.0.6 (OAS2) | here | oas2 | apic oas2 |
1.0.9 (OAS3) | here | oas3 | apic oas3 |
Hint: To get the two "corrected" API specification files:
curl -LO https://raw.githubusercontent.com/ADesprets/petstore/master/materials/swagger-petstore_1.0.6.ok.yaml
curl -LO https://raw.githubusercontent.com/ADesprets/petstore/master/materials/swagger-petstore-openapi-3-0_1.0.9.ok.yaml
Hint: To get the two original API specification files:
curl -LO https://petstore.swagger.io/v2/swagger.json
curl -LO https://petstore3.swagger.io/api/v3/openapi.json
In the following chapters some explanations on how to use the API and the explanations of what was done to make it work. Notice that the original PetStore API re protected with OAuth which requires a separate configuration, for simplicity in this article we remove this security requirement and just replace by API Key. OAuth is simple in API Connect but this is not the purpose of this topic.
After clicking on the Validate button, we see that the API contains error.
Hint: To track the changes I'm going to download the original API on the disk (to get it in yaml format).
After slightly adapting the API everythings is working for more information see at the end the chapter explanations. To facilitate the operation, I provide in this article the corrected API specifications (See original table at the top). So you can simply upload the corrected version and start ot use it.end
Below activating the "corrected" API. Then testing it
When using the Open API V3, the import of the API is slightly different as explained here.
The API does not contain errors but we need to remove the oauth config.
This chapter explains in more details the changes operated. You can also use the diff on the various yaml files located in materials directory.
- Remove the security definition relating to oauth: petstore_auth
- For the Invoke, change the target-url to be target-url:
$(target-url)$(request.path)$(request.search)
instead of target-url:$(target-url)$(request.path)
- Change the security definition for API Key to be:
securityDefinitions:
api_key:
type: apiKey
x-key-type: client_id
in: header
name: X-IBM-Client-Id
- For 10.0.51.x, you have to change the "title": "Swagger Petstore - OpenAPI 3.0" to "title": "Swagger Petstore - OpenAPI 3-0" because . are not accpeted.
The corrected files are here:
OAS2 | OAS3 | |
---|---|---|
10.0.1.9 | here | here |
10.0.5.2 | here | here |
Hint: To get the API specification files after correction:
curl -LO https://github.com/ADesprets/petstore/blob/master/materials/1001-final-swagger-petstore-openapi-3-0_1.0.17.yaml
curl -LO https://github.com/ADesprets/petstore/blob/master/materials/1001-final-swagger-petstore_1.0.6.yaml
curl -LO https://github.com/ADesprets/petstore/blob/master/materials/1005-final-swagger-petstore-openapi-3.0_1.0.17.yaml
curl -LO https://github.com/ADesprets/petstore/blob/master/materials/1005-final-swagger-petstore_1.0.6.yaml