Unify the linting rules for examples to fix any rule collisions and ensure consistent linter messages. In scope of this task are examples for parameter, requestBody, and response objects and their schemas.
This task supersedes T421375: Improve linting - requestBody and response examples - it covers the same scenarios alongside some scenarios not listed in that task.
Current situation
The existing linter rules have been designed in relative isolation and have some overlap and inconsistencies. Some rules are also missing some checks, and either result in false positives or don't flag incorrect definitions of examples in OADs.
Expected result
Validation rules for examples produce consistent and clear recommendations that don't contradict one another and validate for presence of examples in the expected locations in the OAD.
Overview
The purpose of example validation for parameters, request bodies, and responses is to ensure that examples exist for these objects in at least one place in their structure. As a result, the appropriate fields in Swagger UI (and in the API Explorer in the future) are filled with example information, making it easier for users to start interacting with the available endpoints.
Our intention is to only flag as warnings the situations when no examples exist in any of the correct locations for each object. This doesn't mean that we should verify whether examples are specified at only one level, as having examples in many places isn't only correct but sometimes preferred.
The following section describes the locations of examples for parameters, request bodies, and responses that we should support.
Example field validation
For parameters
We consider the parameter to have an example, if one of the following is defined:
- [parameter].example
- [parameter].examples
- [parameter].schema.example
- [parameter].schema.properties.[every individual property].example - Note that most parameters with a schema definition in [parameter].schema will have a simple structure. It's unlikely that an OAD will specify examples for each property. I'm adding this location here for consistency with other validations of the schema object.
- [parameter].schema.$ref, where $ref points to a schema with an example defined in schema.example or schema.properties.[every individual property].example like in the earlier cases.
- [parameter].content.[media object].example
- [parameter].content.[media object].examples - Note that this example isn't supported by Swagger UI (i.e. examples don't render in the sandbox).
- [parameter].content.[media object].schema.example
- [parameter].content.[media object].schema.properties.[every individual property].example
- [parameter].content.[media object].schema.$ref where $ref points to a schema with an example defined in schema.example or schema.properties.[each property].example like in the earlier cases.
Test OADs for these cases are available in the GitLab repository. Note that most of the OAD examples linked in this and the next sections raise the wikimedia-schema-example-recommended warning in addition to any other warnings. This isn't an intended behavior, but I chose not to address these warnings as it would make the OADs more confusing. Modifying wikimedia-schema-example-recommended is in scope for this task.
For request bodies
We consider the requestBody to have an example, if one of the following is defined:
- requestBody.content.[media object].example
- requestBody.content.[media object].examples
- requestBody.content.[media object].schema.example
- requestBody.content.[media object].schema.properties.[every individual property].example
- requestBody.content.[media object].schema.$ref where $ref points to a schema with an example defined either in schema.example, or schema.properties.[every individual property].example like in the earlier cases
Test OADs for these cases are available in the GitLab repository.
For responses
We consider the response to have an example, if one of the following is defined:
- [response].content.[media object].example
- [response].content.[media object].examples
- [response].content.[media object].schema.example
- [response].content.[media object].schema.properties.[every individual property].example
- [response].content.[media object].schema.$ref where $ref points to a schema with an example defined either in schema.example, or schema.properties.[every individual property].example like in the earlier cases
Test OADs for these cases are available in the GitLab repository.
Other notes
- Examples can theoretically exist in response headers. These examples aren't in scope for this task.
- Examples can also exist under schema.items when the schema describes an array. In such a case, the example should be under schema.example so there is no need to introduce validation of schema.items. This is because schema.items.example only supports a single value and the resulting example array would always contain multiple instances of the same item. schema.example allows the example array to contain multiple different items which is a more common scenario.
Proposed solution
Modify the linter rules related to example validation to:
- Return a warning if a parameter, request body, or response is missing all the fields defined earlier, in the relevant sections.
- Return an info message if a parameter, request body, or response only contains schema.$ref and is missing all the other example fields defined in the earlier sections.
- Return a warning if a schema defined in the components object is missing the schema.example field and schema.properties.[every individual property].example fields.
Conditions of acceptance
- Verify that the proposed solution is acceptable and viable
- Plan the best way to reorganize linter rules to achieve the proposed solution
- Implement the solution
- Verify the solution against all the linked examples and any other OADs