GREsau / okapi

OpenAPI (AKA Swagger) document generation for Rust projects
MIT License
631 stars 112 forks source link

Parameter examples generate incorrect OpenAPI schema #112

Open build2stone opened 2 years ago

build2stone commented 2 years ago
#[derive(Serialize, FromForm, JsonSchema)]
#[schemars(example = "example_param")]
struct Param(i32);

fn example_param() -> Param {
    Param(10)
}

#[openapi]
#[get("/example?<param>")]
fn get_param(param: Param) {}

Returns a spec containing

"examples": [
  10
]

instead of

"example": 10

Using rocket-okapi 0.8.0-rc.2

ralpha commented 2 years ago

They are both correct according to the spec. The examples can lists multiple example values. The example (notice the missing s) can denote only one example value. Screenshot from 2022-10-12 13-54-36 Source: https://spec.openapis.org/oas/latest.html#fixed-fields-9

If there is something else I'm missing, let me know.

build2stone commented 2 years ago

Sorry for not including this info from the beginning. I've put my example code here: https://github.com/build2stone/okapi_examples It prints the following spec:

{
  "openapi": "3.0.0",
  "info": {
    "title": "okapi_examples",
    "version": "0.1.0"
  },
  "paths": {
    "/example": {
      "get": {
        "operationId": "get_param",
        "parameters": [
          {
            "name": "param",
            "in": "query",
            "required": true,
            "schema": {
              "examples": [
                10
              ],
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    }
  },
  "components": {}
}

The problem here is that using examples inside a schema object is only supported in v3.1.0, not v3.0.0 (the purported version): https://spec.openapis.org/oas/v3.0.0#fixed-fields-19 vs https://spec.openapis.org/oas/v3.1.0#fixed-fields-19

examples directly within the parameter object is supported in both versions, but appears unrelated.