Rule "ibm-success-response-example" fails for some operations but not others

[michelecurioni]

I'd like to understand why the above rule complains for some operations, but not others, even if I haven't explicitly defined examples in any of the api responses.
It seems that in some cases the rule accepts that an example can be generated based on the schema of the response, and in other cases the schema is not enough.

Is there a way to tell what's missing from the inadequate schemas?

Also, Swagger UI shows auto generated examples for all my operations, so it's difficult to understand what's missing from some schemas

[dpopp07]

There are a couple of conditions the rule looks at to determine if it is even going to look for an example:

1. It must be a success response (status code between 200 and 299)
2. It must have "application/json" content

It then looks to see if the response itself has an example or an examples field, then checks to see if the schema has an example field.

Does that make it more clear? Feel free to let us know if you see any gaps in this approach.

[michelecurioni]

Does the rule ignore responses with "application/hal+json" content?

Would it be possible to make the rule accept specs that have examples defined at schema properties level, rather than at the response level?
For instance, this spec has all the information required to generate examples:

openapi: 3.0.0 
info:
  version: "1.1.0" # semver
  title: aaa
  description: aaa
paths:
  /example-resources:
    get:
      description:  a description
      responses:
        "200":
          description: aaa
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ExampleResource"
components:
  schemas:
    ExampleResource:
      description: an exampleResource
      properties:
        id:
          type: string
          format: uuid
          description: the id of the object
          example: fb53f206-9fee-433a-bc6c-45a3534b9ef1

If I had to explicitly define an example field, I'd incur the risk of making it inconsistent with the schema, and it's a pain to maintain manually.

[dpopp07]

Does the rule ignore responses with "application/hal+json" content?

I think it does, right now. For some other rules, we use a regular expression to support more flavors of JSON content. We should probably use that here, too.

Would it be possible to make the rule accept specs that have examples defined at schema properties level, rather than at the response level?

Yes, that certainly sounds possible. I think we'd have to recursively ensure that an example is defined for every property in the schema (at least, every required property). I agree, that should result in enough information to enable generating complete examples. That said, I'll want to look at our generation tooling to verify it will generate examples without the top-level example being present before changing the rule. Just because it's possible doesn't mean we support it everywhere.