Deprecate in-built Schema support in favour of drf-spectacular

[carltongibson]

There are a number of related issues with schema generation. I’m gathering them here so that they can be addressed together. Closing the original issues.

• Multiple Choice fields don't generate the proper schema #1297
• Various Range filters generate incorrect OpenAPI schema #1292
• I need filter_name passed to get_coreschema_field #1259
• Add support for OpenAPI parameter schema types #1258
• Default filters for foreign keys should document as integers, not strings. #1156
• OrderingFilter causing Parser error: unknown tag when using OpenAPI schema #1135

[sim1234]

How about actually fixing it?

[carltongibson]

As per #1534...

I recommend checking out drf-spectacular if you're working with schemas.

https://drf-spectacular.readthedocs.io/en/latest/readme.html

It's a lot better developed than other options, including the basic in-core support.

I'm likely to deprecate the built-in support in favour of this in the 23.x series.

[carltongibson]

RFC on drf-spectacular: tfranzel/drf-spectacular#862

[tfranzel]

How about actually fixing it?

@sim1234 The reason is actually quiet simple. Generating a solid schema inside django-filter would require adding hundreds of LOC that would solely deal with creating the necessary introspection tooling. Since drf-spectacular already contains all that tooling, it would be reinventing a really intricate wheel here.

[royalroot]

I have a question that belongs loosely to this topic. I use many ChoiceFilters in combination with drf and drf-spectacular.

To get things working I had to put in the field_name of the model (yes that's clear so far) and the choices="Defined Choices" of my model. But when I'm doing this in the docs of drf-spectacular everything is doubled in the examples.
Without choices="Defined Choices" the API is not working.

What am I doing wrong? Can somebody point me in the right direction?

[tfranzel]

@nicro87 you mean doubled in the schema? Please open an issue in https://github.com/tfranzel/drf-spectacular/issues

Provide an (ideally self-contained) example for your filter as well as the resulting schema. This is a complicated feature and examples make it a lot easier to talk about.

[carltongibson]

This was done in #1574. Deprecations will be in v23.2 that I'll roll this ≈week. Built-in schema methods will be removed from the DRF backend in v25.1.

[adamJLev]

how do we migrate this to the new drf-spectacular generated schema to silence the warnings? maybe some info in the docs would be great. thank you!

================================================= warnings summary ==================================================
tests/functional/docs/test.py::test_api_docs_pages_authentication
  /Users/...lib/python3.11/site-packages/django_filters/rest_framework/backends.py:134: RemovedInDjangoFilter25Warning: 
Built-in schema generation is deprecated. Use drf-spectacular.
    warnings.warn(