bad output type for POST exec command in swagger description?

[mxyns]

Hi,
I've been trying to make a Rust wrapper of the clab-api-server to interact with containerlabs programmatically. As soon as I saw you had a swagger API description available I rushed and used the official OpenAPI code generation tool to do that.

Everything has been running smooth except for the API endpoint that allows executing commands on nodes and getting the result: /api/v1/labs/{lab_name}/exec

This endpoint can return either JSON or plain output based on the format query parameter. However, in the current swagger description, the result type seems to always be "string" for result code 200:

  /api/v1/labs/{labName}/exec:
    post:
      consumes:
      - application/json
      description: Executes a command on nodes within a specific lab. Checks ownership.
        Supports filtering by a single node name.
      parameters:
         [...]
      produces:
      - application/json
      responses:
        "200":
          description: Plain text output (if format=plain)
          schema:
            type: string

This makes the OpenAPI code generation tool expect only Strings and not JSON Objects as well. When a JSON object is received (exec?format=json), the generated code tries to parse it as a json string instead of a json object and fails.

I believe that you can describe different output schemas based on the media type: https://swagger.io/docs/specification/v3_0/describing-responses/

I assume that this is not a bug from OpenAPI and just an overlook in the api description but I might be wrong.

[mxyns]

While trying to find a solution I noticed that the swagger file does not pass the openapi tools validation:

max@max: java -jar /tmp/openapi-generator-cli.jar validate -i swagger.yml
Validating spec (swagger.json)
Warnings: 
        - Unused model: models.ClabExecInternalResult
        - Unused model: models.ExecResponse

[info] Spec has 2 recommendation(s)

PS: I am using the latest openapi-generator v7.19.0. For clab-api-server I am using swagger and docker images v0.1.14

[mxyns]

A temporary fix for me has been to change the exec responses to

      responses:
        "200":
          description: Plain text output (if format=plain)
          schema:
            $ref:  '#/definitions/models.ExecResponse'

This makes the model correct for application/json media type but not for plain/text
Hopefully someone could migrate the swagger to OpenAPI 3.0 which seems to allow a different schema for each media type on a request

[FloSch62]

Thanks,
swaggo/swag#1898

Maybe OpenApi 3.0 support will come "soon"

[FloSch62]

fixed by #59

[mxyns]

Maybe OpenApi 3.0 support will come "soon"

That would be amazing!

Thanks for the fix @FloSch62