Improvements to openapi schema generation

[mrginglymus]

This PR addresses a number of issues I've encountered when using the openapi schema generated by DRF to generate API clients in typescript, though they apply equally to any typed client generated from the schemas.

The four issues are, in order of commits:

1. More agressive usage of references, avoiding inlines This ensures that any serializer field is turned into a reference to the relevant schema, no matter how deeply nested.
2. Add output field to serializer method field I have encountered this a number of times, whether something as trivial as a boolean field, or a method field which returns structured data. Being able to express the 'output_field' ensures correct typing of the relationship.
3. Error response schemas Largely for convenience in parsing error responses in clients, this emits an error response based on the structure of the request.
4. Pagination responses - addresses #7299 Bonus that I remembered - output a separate named object for paginated schemas to remove 'inline' responses. Not necessary for list-like responses as client generators are able to handle trivial list-only items.

I have already succesfully used these four changes locally based on the existing released code; however, the code necessary to acheive them is quite ugly as the base AutoSchema lacks the necessary extension points to achieve it due to there being no easy way to hoover up components.

I've not added any extensive tests, although I have updated any existing tests to reflect the new behaviour. Obviously a lot more testing and docs will be needed, but I wanted to get general approval and input on the direction to take the implementation before moving forward.

This replaces https://github.com/encode/django-rest-framework/pull/8417 which contained more substantial changes

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[carltongibson]

As per #8453 I think we should be recommending drf-spectacular at this point, and thinking about deprecating the in-built schema implementation. I'm not sure how much effort it's worth putting into duplicating (but not as well) what drf-spectacular is doing?

//cc @tomchristie

[mrginglymus]

Hi, sorry for letting this slide! I did find the recommendation in #8453 shortly after raising this PR, and found the DRF spectacular already does nearly everything from this PR, so I have switched to using that. I would certainly encourage you to endorse drf-spectacular prominently.

[auvipy]

interesting. so DRF will not have built in OpenAPI support built in in near future?