Add OpenAPI tags to schemas.

[phuongtai]

Checklist

• I have verified that that issue exists against the master branch of Django REST framework.
• I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• This is not a usage question. (Those should be directed to the discussion group instead.)
• This cannot be dealt with as a third party library. (We prefer new functionality to be in the form of third party libraries where possible.)
• I have reduced the issue to the simplest possible case.
• [] I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.)

Steps to reproduce

Recently, I have implemented Swagger with OpenAPI with this code:

from rest_framework.schemas import get_schema_view
...
urlpatterns = [
   path('openapi', get_schema_view(
        title="API for all things test",
        description="API for all things test",
        version="1.0.0"
    ), name='openapi-schema'),
   ...
    path('docs', TemplateView.as_view(
        template_name='swagger-ui.html',
        extra_context={'schema_url':'openapi-schema'}
    ), name='swagger-ui')
]

Expected behavior

APIs should be group by the first element of a path like that

Actual behavior

APIs that grouped by default

[carltongibson]

There are some good suggestions here in #7104 by @phuongtai and #7177 by @bergran.

#7104 has a good default, from the first path segment, which will work in a lot of cases, but not all.
#7177 allows overriding manually, but by adding attributes to the view, which breaks the schema encapsulation.

So...

What I think we need is to:

• Add, test, and document a new AutoSchema.get_tags(path, method) method. This returns a list of strings or dicts, using the path (probably first segment) as a default implementation.
• Then we add a tags kwarg to AutoSchema.init() so that users may manually override the tags, which will cover most cases.

Usage would look like:

class MyView(APIView):

    schema = AutoSchema(tags=["pets"])
    
    ...

You pass a list of string or dicts for your tags.

If you need something more complex, like tags varied by path, or method you override get_tags().

Hopefully that's clear enough to get started. Happy to input on that if someone wants to open a PR.

[dhaval-mehta]

@carltongibson Nice approach.
Can we add a feature to add tags automatically from viewset/apiview name?

[carltongibson]

@dhaval-mehta As I imagine it, you'd override get_tags() to do that. You might make a case that it should be the default option, but I'm inclined towards first path segment as the 80% option.

[dhaval-mehta]

@carltongibson For a medium to a large project, there is a high chance that they have nested routings. If we implement my solution, it will fix problems for nested routing as well. My solution is an addition to the default solution which may lead 80% option to 95% option.

/restaurants/{restaurant_id}/branches/{branch_id}/inspections/{inspection_id}
RestaurantViewSet -> tags = [Restaurant]
BranchViewSet -> tags = [Branch]
InspectionViewSet -> tags = [Inspection]

Will you approve that merge request with the following approach?

1. Allow custom tags as an argument to the init method. (Your solution)
2. If the user has not provided custom tags, generate tags from the name of the viewset. (My solution)
3. If the viewset is not used, use the default solution to generate tags. (@phuongtai solution)

Also, it would be great if you elaborate more about the following line:
You pass a list of string or dicts for your tags. from #7103 (comment)

Can you please elaborate dict part?

[carltongibson]

Tags can be dictionaries. See the spec.