capella-collab-manager
capella-collab-manager copied to clipboard
docs: Add possible exceptions to API documentation
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.
In ReDoc, they are better visible:
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:
Resolves #883.