SMILEY4 / ktor-swagger-ui

Kotlin Ktor plugin to generate OpenAPI and provide Swagger UI
Apache License 2.0
180 stars 33 forks source link

Invalid attributes added to generated JSON #128

Closed runningjustin closed 2 months ago

runningjustin commented 2 months ago

I have noticed that in version 3.3.1 it seems all the values, whether I've explicitly specified or not, are generated for the parameters block. This isn't a bad thing in general, but it is generating invalid JSON for the OpenAPI 3.1 schema. Specifically, the parameters allowEmptyValue and allowReserved are generated for parameters with "in": "path" but these parameters are only valid for query parameters. I feed this generated API into Readme which raises these validation errors.

For example:

"parameters" : [ {
          "name" : "ownerId",
          "in" : "path",
          "description" : "The id of the owner",
          "required" : true,
          "deprecated" : false,
          "allowEmptyValue" : true,
          "explode" : false,
          "allowReserved" : true,
          "schema" : {
            "title" : "String",
            "type" : "string"
          }
        } ],

Relevant parts of the OpenAPI 3.1 spec: image image

runningjustin commented 2 months ago

There's another syntax error in the generation I'm working through. This is an invalid schema name (can't have brackets). Suggestion would be to replace this name with "kotlinArrayString". I am going to try doing this on my side but I think it should generate correctly by default.

Here is what's generated:

"kotlin.Array<kotlin.String>" : {
        "title" : "Array<String>",
        "required" : [ "size" ],
        "type" : "object",
        "properties" : {
          "size" : {
            "title" : "Int",
            "type" : "integer",
            "format" : "int32"
          }
        }
      },

Ideally this would generate as something like this:

"kotlinStringArray": {
    "type": "array"
    "items": {
           "type": "string"
    }
}
runningjustin commented 2 months ago

@SMILEY4 wondering if you have any thoughts on the above. Thanks!

SMILEY4 commented 2 months ago

Hi, thank you for reporting these issues. i just created version 3.4.0 that should fix both of these problems. The problematic attributes are removed by default and I added options to customize the name/path of the schemas more easily. There are also new options for schema paths and titles that are valid for openapi - for paths this is now the default. (see https://github.com/SMILEY4/schema-kenerator/releases/tag/1.2.0

runningjustin commented 2 months ago

Amazing - thank you! I'll give this a try and report back.

runningjustin commented 2 months ago

Version 3.4.0 is a massive improvement in many ways. Thank you! I have another question / issue that I'll post separately.