error-responses-with-drf-spectacular

[ghazi-git]

To use:

• set DRF setting "DEFAULT_SCHEMA_CLASS" to "drf_standardized_errors.openapi.AutoSchema"
• add the following to drf_spectacular setting ENUM_NAME_OVERRIDES:

"ValidationErrorEnum": "drf_standardized_errors.openapi_serializers.ValidationErrorEnum.values",
"ClientErrorEnum": "drf_standardized_errors.openapi_serializers.ClientErrorEnum.values",
"ServerErrorEnum": "drf_standardized_errors.openapi_serializers.ServerErrorEnum.values",
"ErrorCode401Enum": "drf_standardized_errors.openapi_serializers.ErrorCode401Enum.values",
"ErrorCode403Enum": "drf_standardized_errors.openapi_serializers.ErrorCode403Enum.values",
"ErrorCode404Enum": "drf_standardized_errors.openapi_serializers.ErrorCode404Enum.values",
"ErrorCode405Enum": "drf_standardized_errors.openapi_serializers.ErrorCode405Enum.values",
"ErrorCode406Enum": "drf_standardized_errors.openapi_serializers.ErrorCode406Enum.values",
"ErrorCode415Enum": "drf_standardized_errors.openapi_serializers.ErrorCode415Enum.values",
"ErrorCode429Enum": "drf_standardized_errors.openapi_serializers.ErrorCode429Enum.values",
"ErrorCode500Enum": "drf_standardized_errors.openapi_serializers.ErrorCode500Enum.values",

• If you're not overridding the postprocessing hook setting from drf-spectacular, set it to

"POSTPROCESSING_HOOKS": ["drf_standardized_errors.openapi_hooks.postprocess_schema_enums"]

But if you're already overriding it, make sure to replace the enums postprocessing hook from drf-spectacular with the one from this package. The hook will avoid raising warnings for dynamically created error code enums per field.

Notes:

• This is the initial version for generating OpenAPI 3 error responses when using drf-spectacular. It covers the possible 4xx and 500 errors that can be raised by DRF.
• The implementation allows easily customizing the error responses generation. This is possible by using settings for defining which error responses are allowed ALLOWED_ERROR_STATUS_CODES and changing the error response schema if needed ERROR_SCHEMAS. Other than that, the generation logic is separated into multiple methods under AutoSchema making it easy to override specific aspects of the generation process.
• One concern that can be raised: it might be too much to add some responses to every operation (like 401, 406, 415, 500, ...). For that, I would suggest using the description to document the common error responses (description allows markdown, here's an example). Then, remove the corresponding status codes from the ALLOWED_ERROR_STATUS_CODES.

Here's how this looks in swagger UI:
validation_error_example
validation_error_schema

[codecov]

Codecov Report

Merging #4 (48e27ad) into main (abb808b) will increase coverage by 0.29%.
The diff coverage is 99.59%.

@@            Coverage Diff             @@
##             main       #4      +/-   ##
==========================================
+ Coverage   99.39%   99.69%   +0.29%     
==========================================
  Files           6        9       +3     
  Lines         165      649     +484     
  Branches       25      161     +136     
==========================================
+ Hits          164      647     +483     
+ Misses          1        0       -1     
- Partials        0        2       +2     

Impacted Files	Coverage Δ
drf_standardized_errors/openapi_utils.py	99.15% <99.15%> (ø)
drf_standardized_errors/openapi.py	100.00% <100.00%> (ø)
drf_standardized_errors/openapi_serializers.py	100.00% <100.00%> (ø)
drf_standardized_errors/settings.py	100.00% <100.00%> (+4.76%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[mdefeche]

Hello,

I'm interested in this feature, especially the serializers as I already have my own schema class.

Is it still planned ?

Thank you

[ghazi-git]

yep, this feature is still planned since I also need it. However, it just fell down in my priority list. I'll try to make progress soon. I already have some tests that I didn't push. But, as shown in the test coverage report, the amount of code added for error response introspection is more than 3 times the existing code, so it takes a while to get to a decent test coverage. Other than that, I still need to add the docs.

Still, if you only need the serializers, I suggest you just copy them without having to wait (since I don't expect changing them). However, I should mention that the important work in this feature is in the AutoSchema class which might have some small changes depending on what the tests uncover.