Tuesday, April 18, 2023

OpenAPI 3.0 - Model Composition; interesting idea ... only idea now

DRY is one of key principles in software development.

I was happy to see OpenAPI schema can be extended if needed and wanted to benefit from it

"jira_cloud_input": {
"type": "object",
"properties": {
"api_token": {
"type": "string"
},
"name": {
"type": "string"
},
"from": {
"type": "string"
},
"interval": {
"type": "string"
},
"index": {
"type": "string"
}
},
"xml": {
"name": "jira_cloud_input",
"attribute": false,
"wrapped": false
}
},
"jira_cloud_input_disabled": {
"allOf": [
{
"$ref": "#/components/schemas/jira_cloud_input"
},
{
"type": "object",
"properties": {
"disabled": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
}
]
}

This looks nice in Swagger Editor

Relevant endpoint definitions also look as expected:

When python client code is generated in the editor it does not look so nice however (taking sample from README.md)

What is generated from "standard" schema definition looks fine

# create an instance of the API class
api_instance = swagger_client.DefaultApi(swagger_client.ApiClient(configuration))
api_token = 'api_token_example' # str | (optional)
name = 'name_example' # str | (optional)
_from = '_from_example' # str | (optional)
interval = 'interval_example' # str | (optional)
index = 'index_example' # str | (optional)
output_mode = 'output_mode_example' # str | The name of the item to operate on (optional)

try:
api_response = api_instance.splunk_ta_jira_cloud_jira_cloud_input_post( api_token=api_token, name=name, _from=_from, interval=interval, index=index, output_mode=output_mode)
pprint(api_response)
except ApiException as e:
print("Exception when calling DefaultApi->splunk_ta_jira_cloud_jira_cloud_input_post: %s\n" % e)

Unfortunately, where the extension was used lacks of method parameters

# create an instance of the API class
api_instance = swagger_client.DefaultApi(swagger_client.ApiClient(configuration))
name = 'name_example' # str | The name of the item to operate on
output_mode = 'output_mode_example' # str | The name of the item to operate on (optional)

try:
api_response = api_instance.splunk_ta_jira_cloud_jira_cloud_input_name_post( name, output_mode=output_mode)
pprint(api_response)
except ApiException as e:
print("Exception when calling DefaultApi->splunk_ta_jira_cloud_jira_cloud_input_name_post: %s\n" % e)

As a consequence, I need to break DRY rule just to have reliable client code generated.

PS: I do use swagger-codegen-cli-v3 docker image in fact to generate the client code