bug(api): Nested Array Types Generate Swagger Missing `items` Field

[spencercjh]

Problem Description

When a nested array type (e.g., [][]interface{}) is defined in an .api file, the Swagger 2.0 specification generated by goctl lacks the required items field in the array schema, violating the Swagger 2.0 specification.

Reproduction Steps

Create nested-array.api:

syntax = "v1"

type TestResponse {
    Data [][]interface{} `json:"data"`
}

@server (
    prefix: /api
)
service test-api {
    @handler GetTest
    get /test returns (TestResponse)
}

Method 1: Using plugin (old way)

goctl api plugin -plugin goctl-swagger="swagger -filename nested-array.json" -api nested-array.api -dir .

Method 2: Using built-in command (recommended way)

goctl api swagger -filename nested-array.json -api nested-array.api -dir .

Actual Result

Both methods produce the same incorrect output. The generated nested-array.json contains:

{
  "definitions": {
    "TestResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array"
        }
      }
    }
  }
}

Note: The schema for the data field only has "type": "array", missing the items field.

Expected Result

According to the Swagger 2.0 specification, array types must include the items field:

{
  "definitions": {
    "TestResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}

Specification Requirements

Swagger 2.0 Specification (Schema Object):

If type is "array", the items property is required.

OpenAPI 3.0 Specification (Schema Object):

Value MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a Standard JSON Schema. items MUST be present if the type is array.

Impact

1. Generated Swagger documentation cannot pass strict schema validation (e.g., kin-openapi's Validate())
2. Toolchain (such as Swagger UI, OpenAPI generators) may not parse or render API documentation correctly
3. Client code generators may produce incorrect type definitions

Technical Analysis

Related Files:

• tools/goctl/api/swagger/properties.go - Handles type to Swagger property conversion
• tools/goctl/api/swagger/definition.go - Generates definitions
• tools/goctl/api/swagger/response.go - Generates response schemas

Possible Causes:

1. The type parser does not recursively generate the items for inner arrays when processing nested arrays
2. The interface{} type mapping logic may be missing or incomplete
3. The array type conversion code may be missing items field generation

Suggested Fixes:

1. Enhance array type handling logic in properties.go
2. Recursively process nested arrays, generating corresponding items schemas for each layer
3. For interface{} type, at minimum generate {"type": "object"} as items
4. Add unit tests to cover nested array scenarios

Real-World Case

In the stability-alert-center project, the following type definition:

type AlertConfig struct {
    // ...
    NotifyTarget [][]interface{} `json:"notifyTarget"`
    // ...
}

The generated Swagger has multiple instances of missing items, causing OpenAPI validation failures.

[kesonan]

Use goctl api swagger instead.

[spencercjh]

@kesonan Thanks for the suggestion! I've tested with goctl api swagger (built-in command) in goctl 1.9.2, and the bug still exists.

Both the new GOCTL_EXPERIMENTAL parser and the old ANTLR parser produce the same incorrect output:

Test 1: Old ANTLR parser (GOCTL_EXPERIMENTAL=off)

goctl env -w GOCTL_EXPERIMENTAL=off
goctl api swagger -filename test-nested-off.json -api test-nested-array.api -dir .

Test 2: New Go parser (GOCTL_EXPERIMENTAL=on)

goctl env -w GOCTL_EXPERIMENTAL=on
goctl api swagger -filename test-nested-on.json -api test-nested-array.api -dir .

Both produce (with [][]interface{} type):

{
  "data": {
    "type": "array",
    "items": {
      "type": "array"  // ❌ Missing nested items
    }
  }
}

The nested items field is still missing. This is a bug in goctl's Swagger generation logic that needs to be fixed upstream.

Could you please confirm if this is a known issue that will be addressed in a future release?