Ready-made Vs Tailor-made fields in OpenAPI definitions: Part 2

An OpenAPI catalog for WSO2 APIM and Micro-gateway 320

[Source: https://media0.giphy.com/media/1zL7bm3xomm5R5PfRH/giphy.gif]

Supported default fields and WSO2 vendor extensions in OpenAPI Definition

[Source:https://media1.tenor.com/images/eaf6129304674c4d262395fa8d6b8096/tenor.gif?itemid=8039421]

Default Fields

1. Metadata
- OpenAPI version
- Info
2. Servers
3. Paths
4. Parameters
5. Request body
6. Responses
7. Input and Output models
8. Authentication

WSO2 Vendor Extensions

[Source: https://mg.docs.wso2.com/en/latest/concepts/openapi-extensions/]

Enabling WSO2 vendor extensions via Publisher portal

1. x-wso2-basePath

Fig 1: Defining the API context and version in the publisher portal
Fig 2: x-wso2-basePath in the OpenAPI definition

2. x-wso2-endpoints

x-wso2-production-endpoints
x-wso2-sandbox-endpoints
Fig 3: Defining the API endpoint in the publisher portal
Fig 4: Modifying the API endpoint in the publisher portal
Fig 5: x-wso2-production-endpoints and x-wso2-sandbox-endpoints in the OpenAPI definition

3. x-wso2-throttling tier

APIM

  • API Level
Fig 6: Default throttling policies defined in the admin portal
Fig 7: Defining and modifying the API level throttling in the publisher portal
Fig 8: x-throttling-tier extension defined in APIM at the OpenAPI root level for API level throttling
  • Operational Level
Fig 9: Defining and modifying the Operational level throttling in the publisher portal
Fig 10: x-throttling-tier extension defined in APIM at the OpenAPI path level for operational level throttling

MGW

policies.yaml
resourcePolicies:
- 1PerMin:
count: 4
unitTime: 1
timeUnit: min
Fig 11: x-wso2-throttling-tier extension defined in MGW at the OpenAPI root level for API level throttling
Fig 12: x-wso2-throttling-tier extension defined in MGW at the OpenAPI path level for operational level throttling

4. x-wso2-cors

Fig 13: CORS Configuration in the publisher portal
Fig 14: x-wso2-cors extension in the OpenAPI definition

5. x-wso2-response-cache

Fig 15: Response caching configuration in the publisher portal
Fig 16: x-wso2-response-cache extension in the OpenAPI definition

6. x-wso2-disable-security

Please note that the x-wso2-disable-security extension is currently supported in MGW-3.2.0.
Fig 17: Disable operation level security in the publisher portal.
Fig 18: x-wso2-disable-security extension defined at the resource level in the OpenAPI definition
Fig 19: x-wso2-disable-security extension defined at the API level in the OpenAPI definition

7. x-wso2-application-security

1. basic_auth
2. api_key
3. oauth2
Fig 20: Define the security schema in the OpenAPI definition
Fig 21: Using the security schema in the OpenAPI definition
Fig 22: Configure the application-level security
Fig 23: The x-wso2-application-security in the OpenAPI definition
Fig 24: Defining the local scopes in the publisher portal
Fig 25: The defined scopes will be displayed as above in the OpenAPI definition
Fig 26: Bind the scopes to a resource
Fig 27: Resource level security with scopes in the OpenAPI definition
Fig 28: Define the security schema with scopes in the OpenAPI definition
Fig 29: Usage of the security schema with scopes in the OpenAPI definition
Tip:
APIM-3.0.0 supports only the scopes defined in default securitySchema and the latest wum version of APIM-3.1.0 and higher APIM version support the scopes in the custom securitySchema.

1. wso2am-3.0.0 scopes with default securitySchema

Fig 30: Define the default security schema with scopes in the APIM-3.0.0 OpenAPI definition
Fig 31: Usage of the default security schema with scopes in the APIM-3.0.0 OpenAPI definition

2. wso2am-3.1.0 scopes with custom securitySchema

Fig 32: Define the default security schema with scopes in the APIM-3.1.0 OpenAPI definition
Fig 33: Usage of the default security schema with scopes in the APIM-3.1.0 OpenAPI definition

8. x-wso2-auth-header

Fig 34: Configuring the auth header in the publisher
Fig 35: The x-wso2-auth-header in the OpenAPI definition

9. x-wso2-transport

Fig 36: Configuring the transport-level security in the publisher portal
Fig 37: The x-wso2-transports in the OpenAPI definition

10. x-wso2-mutual-ssl

Fig 38: Configuring mutual SSL in the publisher portal
Fig 39: The x-wso2-mutual-ssl in the OpenAPI definition

Bonus Bonanza!

  1. servers field
servers:
- url: "https://my-json-server.typicode.com/saranki/account-json-backend/accounts"
description: "production endpoint"
servers.yaml
x-wso2-production-endpoints: 
urls:
- "https://my-json-server.typicode.com/saranki/account-json-backend/accounts"
wso2-extensions.yaml
servers = schemes + host + basepath

Wrap Up…!

[Source: https://media3.giphy.com/media/d30oLgYQg8xMNlGE/source.gif]

References

--

--

Inquisitive | Senior Software Engineer @ WSO2

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store