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.
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.