Documenting error codes properly in the generated openapi schema?

[Shaun Gosse]

Hi,

We're using the automatic schema generation to produce our openapi documentation of our API.

However, currently the responses just list the success case responses, 200/201.

What should I be doing so that we also have the 403 or other error case responses documented when authentication or lookup fails?

Currently in our code, we throw an exception and DRF converts to the proper response but I don't know how to get this recognized by the auto schema nor where I can go to override to manually add it.

The option I see currently is to just manually add it everywhere via overriding the top-level get_schema method and then basically looping over our responses and such, but this seems wrong in a couple ways: it feels like I should be able to add something custom to the individual view / serializer vs having to do it all globally. And also, seems like there should maybe be some way introspection could pick these up (it's fine if that's just not built yet; I'm just trying to figure out if I'm missing things that are already built-in).

I haven't tried digging into the code yet to figure out what my various options are but I have read over the schema page (https://www.django-rest-framework.org/api-guide/schemas/) and while it's definitely improved my understanding I don't yet know how to approach this.

My next step will be to review the schema tests and figure out options using that as an example.

Thanks,

-Shaun