operation-document-not-primitive

Check operation responses and warn if they are defined as primitive values.

Rule Details

Using primitive values for responses has several drawbacks:

• it does not provide information about response structure
• it does not provide place for extension
• it makes error handling more difficult

The operation-document-not-primitive rule is designed to ensure that each operation’s response in an OpenAPI schema is not a primitive value. This is because response bodies should typically be objects or arrays that allow for more complex and detailed responses.

Configuration

None.

Examples

Good. It is clear that the response body contains.

paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

Bad. It is not cleat what is inside the response. Plain textual description, error message or both ?

paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                type: string

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.