Errors generating REST clients using OpenAPI specification

App Feedback
,
1

  1. What is it about
    I have downloaded the Swagger JSON for the OpenAPI specification from testiny, to generate REST API client code.
    Via the openapi-generator-cli validate command, I have discovered that the specification is faulty and returns errors.

  2. Environment
    Should not matter in this case, but since you asked:

  • Windows 11 Pro x64
  • Windows Powershell
  • openapi-generator-cli using the python wrapper openapi-generator-cli[jdk4py] via pip install --user openapi-generator-cli[jdk4py]
  1. Steps to reproduce
  • Download some form / wrapper of the openapi-generator-cli via https://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
  1. 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
  1. 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.
  1. 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.

2

Regarding the $ref pointing to # instead of a valid URI:

The swagger documentation says, the $ref string value should contain a URI Reference:
https://swagger.io/docs/specification/v3_0/using-ref/

Pointing to # just points to root, but does not name a valid URI.

Regarding the steps property missing items:

I am not 100% sure if I have correctly added all necessary properties, and I was also not sure if there already exists a valid component schema, which it should point to instead.

3

Hello Nikolaus,

Thank you for the comprehensive writeup.

The OA spec is generated automatically by our API service - We will investigate why this doesn’t generate the missing items and why the recursive schema type reference is not working correctly.

Regards,
Michael