Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Parameter examples generate incorrect OpenAPI schema #112

Open
build2stone opened this issue Aug 27, 2022 · 2 comments
Open

Parameter examples generate incorrect OpenAPI schema #112

build2stone opened this issue Aug 27, 2022 · 2 comments
Labels
okapi This affects the okapi crate

Comments

@build2stone
Copy link

#[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
Copy link
Collaborator

ralpha commented Oct 12, 2022

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
Copy link
Author

build2stone commented Oct 14, 2022

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.

@ralpha ralpha added the okapi This affects the okapi crate label Dec 4, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
okapi This affects the okapi crate
Projects
None yet
Development

No branches or pull requests

2 participants