-
What is it about
I have downloaded the Swagger JSON for the OpenAPI specification from testiny, to generate REST API client code.
Via theopenapi-generator-clivalidatecommand, I have discovered that the specification is faulty and returns errors. -
Environment
Should not matter in this case, but since you asked:
- Windows 11 Pro x64
- Windows Powershell
openapi-generator-cliusing the python wrapperopenapi-generator-cli[jdk4py]viapip install --user openapi-generator-cli[jdk4py]
- Steps to reproduce
- Download some form / wrapper of the
openapi-generator-cliviahttps://openapi-generator.tech/docs/installation - Execute
openapi-generator-cli validate -i https://app.testiny.io/api/v1/swagger.json - Or try to generate a REST client from the OpenAPI specification via
openapi-generator-cli.exe generate -g python -i https://app.testiny.io/api/v1/swagger.json -o tmp
- Expected result
- Validation using OpenAPI generator should not result in an error
- Generation of a REST client should be successful when using the Public Release of the OpenAPI specification
- Actual result
openapi-generator-cli.exe validate -i https://app.testiny.io/api/v1/swagger.json
Validating spec (https://app.testiny.io/api/v1/swagger.json)
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
[main] ERROR o.o.codegen.utils.ModelUtils - Undefined array inner type for `null`. Default to String.
[main] ERROR o.o.codegen.utils.ModelUtils - Undefined array inner type for `null`. Default to String.
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
[main] WARN o.o.codegen.utils.ModelUtils - Failed to get the schema name: #
Errors:
- attribute components.schemas.AutomationTestCase.items is missing
Warnings:
- Unused model: FkIds
- Unused model: FkIdsNullable
- Unused model: DataCloneResult
[error] Spec has 1 errors.
- Error logs and/or visual proof
- see above
- Potential fix/solution see below
The warnings occur, because the "map" property of "MapJoin" does a self schema reference to MapJoin using #.
Using # as a schema name for $ref alone is not valid, and it would actually require having a fully qualified path in the form of:
"$ref": "#/components/schemas/MapJoin"
(if I’m not completely mistaken, please enlighten me if I am)
To fix it, I have replaced the map property with this:
"map": {
"oneOf": [
{
"$ref": "#/components/schemas/MapJoin"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/MapJoin"
}
}
],
"description": "Nested mapping starting from one of the member entities of this mapping"
}
An actual error in the validation was the missing items property in AutomationTestCase:
"AutomationTestCase": {
"type": "object",
"properties": {
…
"steps": { ← array…
"description": "The steps property",
"type": "array", ← …but no "items"
"nullable": false
},
…
}
}
To fix that, I have rewritten it as:
"AutomationTestCase": {
"type": "object",
"properties": {
…
"steps": {
"description": "The steps property",
"type": "array",
"items": { // <- add this block
"type": "object",
"properties": {
"id": { "type": "string" },
"title": { "type": "string", "maxLength": 1000 }
},
"required": ["title"]
},
"nullable": false
},
…
}
}
Changing these things resulted in a successful generation of a REST client using the specification.
Just wanted to let you know about that, maybe it’s something you can fix in the original api/v1/swagger.json (Sadly I can’t post direct links)
Due to these errors, I cannot create an automated client generation based on the public URL, which would help tremendously in keeping an up-to-date base client package on our end.
I’d suggest using openapi-generator-cli validate in your CI/CD to mitigate those effects in public release.
