docs: Add possible exceptions to API documentation

[MoritzWeber0]

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.

[github-actions]

A Storybook preview is available for commit 02d1ae5.
View Storybook
View Chromatic build

[codecov]

Codecov Report

Attention: Patch coverage is 72.92225% with 101 lines in your changes missing coverage. Please review.

Project coverage is 79.73%. Comparing base (52cfc68) to head (45512d5).
Report is 146 commits behind head on main.

Files	Patch %	Lines
...nd/capellacollab/core/authentication/jwt_bearer.py	25.00%	9 Missing ⚠️
...ellacollab/settings/modelsources/t4c/exceptions.py	75.00%	6 Missing ⚠️
...pellacollab/settings/modelsources/t4c/interface.py	37.50%	5 Missing ⚠️
backend/capellacollab/core/responses.py	87.09%	2 Missing and 2 partials ⚠️
backend/capellacollab/projects/routes.py	33.33%	3 Missing and 1 partial ⚠️
...d/capellacollab/core/authentication/injectables.py	75.00%	3 Missing ⚠️
...lab/projects/toolmodels/modelsources/t4c/routes.py	40.00%	3 Missing ⚠️
backend/capellacollab/sessions/routes.py	66.66%	3 Missing ⚠️
...ttings/modelsources/t4c/repositories/exceptions.py	72.72%	3 Missing ⚠️
...b/settings/modelsources/t4c/repositories/routes.py	25.00%	3 Missing ⚠️
... and 38 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1569      +/-   ##
==========================================
+ Coverage   79.52%   79.73%   +0.20%     
==========================================
  Files         172      185      +13     
  Lines        5778     5971     +193     
  Branches      666      666              
==========================================
+ Hits         4595     4761     +166     
- Misses       1034     1064      +30     
+ Partials      149      146       -3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[dominik003]

LGTM! There are just a few minor comments that should be addressed before we merge this.

[sonarcloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud