GREsau/okapi

Parameter examples generate incorrect OpenAPI schema

build2stone opened this issue · 2 comments

#[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

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.

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.