Rule 'Every DTO must define at least one example'

[mtrossbach]

I’ve noticed that the linter rules currently check examples only at the object level. While this is useful for overall consistency, there are scenarios where property-level example validation would be beneficial. Specifically, I’d like to propose an enhancement that allows to validate examples associated with individual properties within an OpenAPI document.

Use Case: Consider the following situation:

• An API specification contains multiple properties within an object.
• Each property has its own example value.
• Some properties are defined globally and have their own property-specific example attached (e.g. 'createdAt' or 'updatedAt' attributes).

Expected Behavior: I suggest extending the rule to validate examples at both the object level and the property level. This enhancement would provide more granular control over example validation.

Benefits:

• Fine-Grained Validation: Property-level example checks would help maintain consistency within individual properties
• Improved API Quality: By validating property-level examples, we can support to reference properties which are used in multiple object without specify the relevant examples again for each occurrence

Example: Suppose we have an OpenAPI schema like this:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /demo:
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Demo'
components:
  schemas:
    timestamp:
      type: string
      format: date-time
      readOnly: true
      description: >
        This value is auto generated by the API [RFC 3339, section
        5.6/ISO8601](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)
      example: '2022-09-25T10:43:28.000Z'
    Demo:
      type: object
      properties:
        id:
          type: string
          description: ID of the source
          example: ce49715f-784b-45fd-b6c4-56f8435237a2
        createdAt:
          $ref: '#/components/schemas/timestamp'
        updatedAt:
          $ref: '#/components/schemas/timestamp'

[markbrockhoff]

Hi @mtrossbach thanks for opening this issue. I think this is a valid point of concern and will take it with me into our next maintainer round to discuss it with the other maintainers.
As I think there's a good chance this could be changed, would you be willing to provide a PR implementing the suggested change? :)