feat: warn for missing response examples

[barrett-schonefeld]

Purpose:

• Establish working pattern for writing custom functions such that, when users extend the ibm:oas ruleset, our custom functions are still findable by Spectral.
• Tooling to generate documentation relies on response examples provided either in the schema or "next to" the schema at response level. Warn about responses that do not provide examples in these locations.

Changes:

• Create a custom Spectral rule to warn about missing response examples
• Create a custom Spectral function to check if a response example provided in the locations supported by the code that generates documentation.

Tests:

• Add tests to ensure no warning given when a response example is provided.
• Add a test to ensure a warning is given when no response example provided.

Docs:

• Document the response-example-provided rule in docs/spectral-rules.md

Possible changes:

• Include more than application/json responses. To do this, we would change the given field of the rule from $.paths[*][*].responses[*].content.application/json to $.paths[*][*].responses[*].content[*].
• May want to condense the error message. I had writer's block, so I went with a verbose description initially.

[dpopp07]

Looks good to me!

[mkistler]

This looks good but there's one more detail that you will need to handle. In OpenAPI 3.0 they introduced examples on parameters, request bodies, and response bodies. examples is a slightly more elaborate way to provide an example -- you can include not just the example value but also a description and summary. You can also have multiple named examples.

So in addition to checking for example you should also check for examples and only issue the message if neither is present.

[barrett-schonefeld]

This looks good but there's one more detail that you will need to handle. In OpenAPI 3.0 they introduced examples on parameters, request bodies, and response bodies. examples is a slightly more elaborate way to provide an example -- you can include not just the example value but also a description and summary. You can also have multiple named examples.

So in addition to checking for example you should also check for examples and only issue the message if neither is present.

I believe the current rule does allow for examples. In the negative test, the test that defines response examples and expects no warnings, one response uses examples to provide a response example. This links to the response that uses examples.

[mkistler]

Thanks Barrett, I missed that. Looks like you have it covered. Nice work!

[mkistler]

Looks good! 👍

[dpopp07]

🎉 This PR is included in version 0.38.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀