example for OpenAPI 3.0

[sseemayer]

Thanks a lot for your amazing work on schemars and okapi!

I am using schemars through rocket_okapi to auto-generate docs for an API that I am writing. For this, I would like to give some meaningful examples for the parameters in my request JSON body, but I seem to have hit a conflict between the JSON Schema Validation specification and the OpenAPI 3.0 specification.

The Schema object in OpenAPI 3.0 expects the example for a Schema object to be placed in an example key containing a single example, as opposed to the examples array of example objects that seems to be currently generated by schemars. OpenAPI 3.0 does not allow examples while JSON Schema Validation doesn't seem to support example.

I have tried to generate an openapi.json using schemars with a documentation like so as advised in the attribute documentation for schemars:

fn schema_example_identifiers() -> Vec<String> {
    vec!["my_id1".to_string(), "my_id2".to_string()]
}

fn schema_example_request() -> EntryRequest {
    EntryRequest {
        ids: schema_example_identifiers(),
    }
}

#[derive(serde::Deserialize, serde::Serialize, JsonSchema)]
#[schemars(example = "schema_example_request")]
struct EntryRequest {
    /// A list of entries from the database
    #[schemars(example = "schema_example_identifiers")]
    ids: Vec<String>,
}

The generated openapi.json does contain "examples" entries for EntryRequest:

"schemas": {
      "EntryRequest": {
        "examples": [
          {
            "ids": [
              "my_id1",
              "my_id2"
            ]
          }
        ],
        "type": "object",
        "required": [
          "ids"
        ],
        "properties": {
          "ids": {
            "description": "A list of entries from the database",
            "examples": [
              [
                "my_id1",
                "my_id2"
              ]
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },

However, the examples don't show up in the Swagger UI. If I copy-paste the openapi.json to Swagger Editor, it tells me that "examples" is not a valid field:

Everything works fine in Swagger Editor / Swagger UI after I rename examples to example and change from an array of example to a single example:

    EntryRequest:
      example:
        ids:
            - my_id1
            - my_id2
      type: object
      required:
        - ids
      properties:
        ids:
          description: A list of entries from the database
          example:
            - my_id1
            - my_id2
          type: array
          items:
            type: string

From trying to understand the schemars and okapi codebases, I can see that examples could additionally get passed into the schema object using the extensions member of okapi::openapi3::Parameter structs, but I have no idea how to do this from within my API.

Could you please advise me how I could get the examples to show up correctly? If you would like to mentor me making a contribution to schemars or okapi to add support for the example field, I would also be interested in helping out.

[sseemayer]

I realized that this is already covered in GREsau/okapi/issues/11 .

Upgrading to

rocket_okapi = "0.6.0-alpha-1"
okapi = "0.5.0-alpha-1"
schemars = "0.8.0-alpha-4"

fixed the issue.