As we're starting to check into linting our OpenAPI spec, we should make sure the generated specs are passing requirements.
There are two main issues taht should be directly fixed with the component schemas, as they are being referenced ($ref) throughout the spec:
| Subject | Repo | Branch | Lines +/- | |
|---|---|---|---|---|
| [WIP] REST API spec: Add "examples" to response components | mediawiki/core | master | +27 -5 |
Change #1269058 had a related patch set uploaded (by Mooeypoo; author: Mooeypoo):
[mediawiki/core@master] [WIP] REST API spec: Add "examples" to the response components
I've added an example and descriptions to the response component. The OpenAPI section looks like this now:
"components": {
"schemas": {
"boolean-param": {
"type": "boolean"
},
"enum-param": {
"type": "string"
},
"integer-param": {
"type": "integer"
},
"float-param": {
"type": "number",
"format": "float"
},
"double-param": {
"type": "number",
"format": "double"
},
"password-param": {
"type": "string"
},
"string-param": {
"type": "string"
},
"timestamp-param": {
"type": "string",
"format": "mw-timestamp"
},
"upload-param": {
"type": "string",
"format": "mw-upload"
},
"expiry-param": {
"type": "string",
"format": "mw-expiry"
},
"namespace-param": {
"type": "integer"
},
"title-param": {
"type": "string",
"format": "mw-title"
},
"user-param": {
"type": "string",
"format": "mw-user"
},
"array-param": {
"type": "object"
},
"GenericErrorResponseModel": {
"description": "Generic error response body",
"required": [
"httpCode"
],
"properties": {
"httpCode": {
"type": "integer",
"description": "HTTP status code of the error response"
},
"httpMessage": {
"type": "string",
"description": "HTTP status message of the error response"
},
"message": {
"type": "string",
"description": "A human-readable error message, useful when no message translations are available"
},
"messageTranslations": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "A map of language codes to human-readable error messages, for clients that can use them"
}
}
}
},
"responses": {
"GenericErrorResponse": {
"description": "Generic error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericErrorResponseModel"
},
"examples": {
"genericErrorResponse": {
"summary": "Generic error response example",
"description": "Example payload for generic error responses.",
"value": {
"httpCode": 500,
"httpMessage": "Internal Server Error",
"message": "An unexpected error occurred",
"messageTranslations": {
"en": "An unexpected error occurred",
"es": "Ocurrió un error inesperado"
}
}
}
}
}
}
}
}Which renders in the RestSandbox properly:
However, the linter now returns this error: wikimedia-schema-example-recommended which, if I change the format of the example to be per property, seems to collide with wikimedia-paths-parameter-example-exists .
I'm not sure if we have a linter rule-collision or if there should be a specific exception/consideration with the components section, if nothing else, since it doesn't have parameters, it has properties.
It's not exactly a collision, but the example validation seems to need a bit more work. The way we originally defined the rules was somewhat in isolation from one another, so some interactions between objects might not be accounted for.
Generally, it makes sense to verify the example/examples under parameters and example in the schema component separately. The latter is reusable and could potentially be referenced under a parameter without an inline example. Also, it's not a bad practice to have examples defined on multiple levels. The intention behind our rules was to ensure there's an example defined on at least one level, but it could be defined on multiple levels - e.g. like in the OAD example, where one example is defined under application/json and another under the schema linked via reference in line 579. These examples don't even have to be consistent because Swagger UI seems to only display examples from one level.
That said, I think it would make sense to unify the example validation. My earlier task, T421375: Improve linting - requestBody and response examples, addresses some problems in this area but not all of them, so I'll rewrite it with a proposed, more broad solution.
For this task, you can either define examples at multiple levels to resolve the redundant linting messages, or just at one level, as that's going to be the intended validation.