Edit the Rocket OpenAPI Responses

[NewtTheWolf]

Currently, the documentation includes only one possibility for certain status code responses (e.g., 403), but multiple cases can lead to the same status code. We should either make the responses more generic or document all possible cases for each status code. This approach will depend on what is feasible with OpenAPI.

I’m also facing a broader issue with custom error handling. My project uses custom error responses that follow a different schema than the standard Rocket responses. While it’s possible to create Rocket catchers to handle errors like 401 and 403 with custom responses, I’m not sure how to document these properly in OpenAPI for all relevant status codes.

Questions:

1. Is it possible to overwrite the default documentation for any status code response (e.g., 401, 403, etc.) to reflect custom error responses in OpenAPI?
2. Can we change the key for status codes in OpenAPI? For instance, instead of using 403, we could try something like 403-zitadel to represent different cases for the same status code. How would this affect the documentation and overall schema?
3. How can we ensure that Rocket’s error catchers with custom responses are properly integrated and represented in the OpenAPI documentation without losing consistency?

Suggestions:

• We should investigate how to either generalize each status code response or fully document all possible cases for each status code (e.g., 403 for multiple cases).
• Explore options for overwriting default keys or adding custom keys for specific status code cases (e.g., 403-zitadel).
• Once the approach is clear, I’d be happy to take on the implementation!

I’m raising this issue to gather input on these questions before proceeding with the implementation.