OpenAPI parameter description vs parameter schema description

user_3571100 0
Viewed 391

In OpenAPI 3.0, I'm wondering what the difference is when describing parameters. For example, what is the difference between descriptions "Foo" and "Bar" below? Is the one for "Foo" more for the semantics of the parameter and the one for "Bar" more for the syntax, if that makes sense? Should just one be used generally (and which if so)?

{
  "name": "someParameter",
  "in": "query",
  "description": "Foo",
  "schema": {
    "type": "string",
    "description": "Bar"
  }
}
openapi
1 Answers

The parameter description is specified by the description in the parameter itself.

It just so happens that parameters use a schema to define the data type, and schemas can have their own description. In the context of parameters, you can think of the schema-level description as the description of the parameter's data type.

The two descriptions are semantically separate. Schema-level decription is NOT a fallback for missing parameter description.

Here's another example:

paths:
  /users/{id}:
    delete:
      summary: Delete a user
      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user you want to delete.
          schema:
            type: string
            format: uuid
            description: >-
              A unique identifier in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".

In practice, parameters usually don't have a schema-level description specified because it's often redundant.

user_1131160
Related