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.