Update schema generation doc & add deprecation notice #8453

[tfranzel]

As discussed in #8453, this PR re-arranges some aspects of the schema documentation.

• schema.md: add deprecation notice
• documenting-your-api.md: add deprecation notice
• documenting-your-api.md: push deprecated approach below the recommended one
• documenting-your-api.md: adapt intro text
• documenting-your-api.md: recommend drf-spectacular
• documenting-your-api.md: make clear that drf-yasg is OpenAPI 2

[carltongibson]

Hi @tfranzel thank for this. I think it's the way to go yes.

Ultimately it's @tomchristie's call so we'll defer to him here.

🎁

[tomchristie]

Wonderful. 💛

[tomchristie]

@tfranzel - Since this is your PR, I've sent you an invite to the @encode/django-rest-framework team. Please don't feel obligated to accept. If you do choose to, then you'll have permissions to merge/approve this (and other) PRs. If you'd prefer not to, then one of the other maintainers will merge this pull request sometime soon.

[tfranzel]

thank you @tomchristie for the invitation. happy to join ❤️

[auvipy]

BTW, I am still willing to merge small edge case fixes for built in openapi support

[carltongibson]

I think when this is deployed we could likely point back here (or the discussion maybe as better) and close related PRs and Issues. 🤔 (Bottom line is folks are better off moving to drf-spectacular than waiting for a not as good improvement in the in-built introspection.)

I'd suggest the CoreAPI generation could simply be removed at this point. I guess the OpenAPI generation should still be moved out (with tests and everything) to a package so folks can swap an import/setting/etc to use if they need.

I'd guess that all that should remain in schemas should just be the ViewInspector base class and the DefaultSchema helper class. (Would need to verify.)