reana
reana copied to clipboard
create OpenAPI docstring checker WRT possible jsonify statuses
Current status
Currently, we have some situations as in r-j-controller's create_job()
endpoint returning 403 in some cases:
try:
job_obj = job_manager_cls(**job_request)
except REANAKubernetesMemoryLimitExceeded as e:
return jsonify({"message": e.message}), 403
However, the 403 response is not documented in create_job()
's docstring:
responses:
201:
description: Request succeeded. The job has been launched.
schema:
type: object
properties:
job_id:
type: string
examples:
application/json:
{
"job_id": "cdcf48b1-c2f3-4693-8230-b066e088c6ac"
}
400:
description: >-
Request failed. The incoming data specification seems malformed.
500:
description: >-
Request failed. Internal controller error. The job could probably
not have been allocated.
This means that we don't "advertise" a possible 403 reply to the client of this API, so our API documentation is kind of incomplete.
Expected status
It'll be good to make sure that every jsonify(...), NNN
response is well represented in our OpenAPI specs, i.e. in the docstring of each endpoint, so that our OpenAPI could be "complete" towards a future 1.0 release. (Coming after create/validate is moved server-side.)
In order to facilitate discovering these "incomplete" endpoints, it would be good to write a helper function that would:
- for a component such as r-j-controller, walk through REST blueprint functions;
- identify
jsonify(), NNN
responses of the function; - check if this NNN response status is well defined in the docstring;
- if yes, good!
- if no, warn the developer to add it.
Implementation notes
We could either use some Python AST parsers to help process the code, however even a quick and dirtly regexp matching looking for jsonify()
and their locations could be fit for the purpose.
We could plug the newly created OpenAPI checker function into either reana-dev check-openapi -c r-j-controller
integration testing CLI, or even to each component run-tests.sh
.