tegral-openapi-ktor form body content type

[dmorillas]

First of all my apologies if this is not the best place to do it, but I haven't found any other.

Second, thanks for this plugin. It's not easy to find a plugin for ktor that generates automatically the openUI documentation.

And then, to my question / issue.
I'm trying to describe in my API one endpoint which expect a form with several properties, one of them a File to upload and another one a JSON payload with information about that file.

Going through your documentation I've assumed that the way to define this is by

body {
    description = "Video to upload"
    required = true
    form {
    }
}

But I haven't found anywhere in the documentation or the code what I need to put within the "form" to define the properties expected in the body (in my case the File and the String with the payload). Am I in the right direction? Is there anything missing in the plugin? Am I missing something?

Thanks.

[utybo]

Hi! I'm not sure how your file is transmitted, but it could probably be something like this:

data class VideoUpload(
    val file: ByteArray, // I'm not sure what this should be or how this is transmitted
    val payload: String
)

body {
    // ...
    form {
        schema<VideoUpload>()
    }
}

This will not give you much information on the content of the payload, but it should be enough to make it work in Swagger. If you already have a data class that the properties get parsed into, you can use it as-is in your schema<>(). Otherwise, if you know the OpenAPI definition you may have to resort to building Swagger Core schemas, which give you all the flexibility of the original JSON files.

To be fair, I have never done things like file uploads with Swagger, so I'm not sure if I can be of much help here :/

[dmorillas]

Hi!

It is transmitted via a "multipart/form-data"
I have never done it before, that is why I don't know who to do it either :)

I found this page in swagger documentation in how to define it: https://swagger.io/docs/specification/describing-request-body/file-upload/ for version 3

It seems to be defined as a parameter of type form, but I don't see the way to do it with your library.

[dmorillas]

I have found this way to do it:

body {
    description = "..."
    required = true
    "multipart/form-data" content {
        schema = MapSchema()
            .addProperty("file", FileSchema().description("The file to upload"))
            .addProperty("payload", JsonSchema().description("The payload"))
    }
}

which is what I was looking for and the resulting yaml file is in the same format as openAPI spec.

The only issue I have now is that I don't see how I can link an object to the JsonSchema like it can be done with
json { schema<RequestExample>() }

[utybo]

The only use of "linking a class" like this is for generating the schema. This is not needed if you manually create the schema like you're doing here.

If you mean adding an object as an example, this should still be doable via example = ... in the content { ... } block