Description

As we expand our OpenAPI style guide and define linting rules, it is helpful to have an OpenAPI description (OAD) file that we can easily use for testing rule compliance and socializing best practices.

This OAD is intended to have examples that cover every linting rule, and can be used as a reference. We may introduce automated testing to verify linting behavior, as the OAD should always pass all rules. Additionally, the simplified OAD will create an easier route to test or debug new rules than live OADs. It will also be useful to demonstrate simple examples of expected patterns, which will help guide teams who wish to follow the standards, potentially including references to "good" examples in error messages.

Conditions of acceptance

• Create an example OAD that can be used for testing and demonstrating desired patterns across teams.
• Clearly indicate that it is a test document. The content should not be something that could be mistaken for an actual Wikimedia service. There are a few suggestions to accomplish this, but open to other ideas:
  • Follow the "pet shop" example that is frequently used to demonstrate OpenAPI tools.
  • Name the objects after the rules we are defining for clear example mapping (this is half baked and might get tricky, but could be useful).
  • Pick any other "fun" example that can demonstrate functionality without risking Wikimedia domain conflicts or confusion.
• Determine where we should house the OAD, so that it is discoverable and we can ensure that it remains up to date as new rules are introduced.
  • The OAD example is currently under repos/technical-documentation on GitLab, but this is not the final location. We're discussing the best location for the example in T419576.
• Work with Moriel to determine if/how we might use it for automated linter testing.
  • This discussion continues in T419576.

[OAD]: Per OpenAPI Initiative Glossary page (CC BY 4.0):

OpenAPI Description (OAD): One or more documents written according to a specific version of the OpenAPI Specification, that together describe an API