capella-collab-manager icon indicating copy to clipboard operation
capella-collab-manager copied to clipboard

docs: Add possible exceptions to API documentation

Open MoritzWeber0 opened this issue 9 months ago • 3 comments

The Collaboration Manager backend can throw a bunch of different errors. Those errors were only documented in the code by scanning the complete call trace, which is unintuitive for users who just want to talk to the API.

Therefore, I've migrated all legacy occurrences of fastapi.HTTPException to our own exception format. Those exceptions can be registered as response for a route using the responses attribute. A helper function api_exceptions can be used to automatically translate the exceptions to the OpenAPI format. When registered, the exceptions are automatically added to the API documentation.

This PR mainly focuses on the initial implementation of the behaviour and doesn't register exceptions for all routes. However, I did it for some routes, e.g. the "Request session" route, which can be used as example.

In the API documentation, exceptions are grouped by status codes. The generated responses are visible in the generated documentation clients. The large amount of error responses might be too bloated for some generated clients, e.g. our frontend client. Therefore, the addition of error responses in the OpenAPI schema can be disabled by setting the environment variable CAPELLACOLLAB_SKIP_OPENAPI_ERROR_RESPONSES=1.

In SwaggerUI, the individual schemas slightly hidden. They are not displayed in example section, instead, you have to navigate to "Schema" to see all available error responses.

image

In ReDoc, they are better visible:

image

The best option is the right side in the ReDoc documentation where you can select the error in a dropdown to see the the returned JSON: image

Resolves #883.

MoritzWeber0 avatar May 15 '24 10:05 MoritzWeber0