Possible solution for tags generation

[dhaval-mehta]

This merge request adds logic to generate open API tags automatically. It also allows the user to override auto-generated tags as an argument to the constructor of AutoSchema. This solution will not break the encapsulation of schema generation. Inspiration: #7103 (comment)

There is another merge request(#7182) with a possible solution. You can merge whichever solution is the best.

This Fixes: #7103
This closes: #7104 & #7177

[kevin-brown]

In general I'm +0 on these changes. I've got one in-line review comment about being consistent in how we generate the default tag names.

[dhaval-mehta]

In general I'm +0 on these changes. I've got one in-line review comment about being consistent in how we generate the default tag names.

Thanks for your suggestion. I have done given changes. Additionally, I have done the following changes:

1. People use - or _ to separate words in URL (example: order-items or order_items). To make everything consistent, I will replace all - or _ with white space.

[dhaval-mehta]

@carltongibson I await your valuable reply at your earliest convenience.

[tomchristie]

I wonder if we ought to just use the path style as the default case?

I think that'd be more obvious, more consistent across a code base, and a little more simple.

[dhaval-mehta]

Sure. I will implement the path style as the default case.

[carltongibson]

Yes, I think the default implementation should use the path. Folks can pass tags, or subclass for something cleverer.

[tomchristie]

Looks like there's some great stuff here. I'd personally like to see it start slimmed down as much as possible.

[carltongibson]

Hi @dhaval-mehta. Yes, I can see that you like viewsets and want this particular implementation. But a lot of people don't use viewsets at all. And there are many different configurations and conventions. I'm just not convinced that favouring this one particular approach is correct. I will think on it.

[tomchristie]

rather than just going with the much simpler path approach, and letting folks do something different

Seconded. 😃

[dhaval-mehta]

Hi @dhaval-mehta. Yes, I can see that you like viewsets and want this particular implementation. But a lot of people don't use viewsets at all. And there are many different configurations and conventions. I'm just not convinced that favouring this one particular approach is correct. I will think on it.

Should I remove viewset specific implementation?

[carltongibson]

Hey @dhaval-mehta. Yes, I think so, please. Let's just go with the path approach.

Folks can create a subclass if they use viewsets heavily and set settings.DEFAULT_SCHEMA_CLASS to have it used everywhere by default.

[dhaval-mehta]

Hey @dhaval-mehta. Yes, I think so, please. Let's just go with the path approach.

Folks can create a subclass if they use viewsets heavily and set settings.DEFAULT_SCHEMA_CLASS to have it used everywhere by default.

I have removed the viewset specific code.

[dhaval-mehta]

Hey @dhaval-mehta. Yes, I think so, please. Let's just go with the path approach.

Folks can create a subclass if they use viewsets heavily and set settings.DEFAULT_SCHEMA_CLASS to have it used everywhere by default.

Hi @carltongibson, This is a nice idea. With your permission, I would like to add this idea in documentation with an example.

[dhaval-mehta]

Hi, @carltongibson I am working on the global tag object, where users can pass dict as a tag. I request the following you.

1. If you think everything is good, merge this PR because:

   1. I am going to open a PR that has this code + global tag objects. If you won't merge then these changes will come as the difference in that PR.
   2. Possible merge conflict may come with Openapi custom operation name #7190 in schemas.md

2. My approach for global tag objects is:
   allow users to pass a dict as tags to the schema generator class. In this case, we need to override get_schema_view and allow users to pass a custom generator instance (as of now, only class can be passed.)
   If you think my approach needs any changes, kindly let me know.

[carltongibson]

Hi @dhaval-mehta Slowly, slowly. 🙂 Let’s finish this off before moving on. I need time to review it finally and go over the docs changes. Sorry if that’s a bit slow for you, but you have to remember I do this in my free time, and alas I’m not going to review on the weekend.

Then we should discuss further changes in an issue before spending time on code. Firstly, how much demand is there really for the dict format of tags? It might be that we choose to not support it.

[dhaval-mehta]

Sorry. I was unaware about this situation. I am working in start up where code is running on production just 2-3 days after PR. Anyway thank you so much for your efforts.

[carltongibson]

No problem. Therein lies the difference between comercial software and open source. 🙂

Thank you for your efforts on this one. We will get it in.

[tomchristie]

Looking great. @carltongibson let me know if you'd like my time on this too.

[carltongibson]

It’s on my list for this week.

[carltongibson]

Hi @dhaval-mehta.

Good work on this one, thank you! 🥇

Outdated.

[duncanmcdowell]

@dhaval-mehta where did you land on global tags generation. I'm currently looking to implement logic on this but don't want to re-invent the wheel if others have made good progress.

[dhaval-mehta]

@carltongibson I have 2 different approaches for global tag generation.

1. accept global tags as an argument to SchemaGenerator.
2. Guide users on how to create a subclass and override schema generation to generate global tags. For example https://github.com/encode/django-rest-framework/pull/7268/files#diff-6d2713ae8040f965de07518cc4ef8a95R187

I am personally inclined with the approach: 1

[carltongibson]

Yep, currently you'd need to override get_schema().

Happy to add some args to SchemaGenerator in principle for the most common cases. Not sure if tags counts there or not. (Likely yes?)

What I want to avoid is a argument for every possible option: that way lies madness. Keep the interface clean for the common cases that face most users. Subclassing isn't hard for the few that need the more exotic options.

[dhaval-mehta]

SchemaGenerator deals with Open API object

I believe only 2 fields tags and security will be used widely and we have not implemented them. Hence I am not expecting more arguments to SchemaGenerator.

For mid to big size of projects & for companies with multiple teams, the global tags are a must. I think adding tags as a parameter to SchemaGenerator is not a bad idea.

[carltongibson]

Hey @dhaval-mehta. That sounds reasonable. Fancy doing a PR for those either of you? Thanks!

[dhaval-mehta]

@carltongibson I will pick this task today.

[carltongibson]

@dhaval-mehta One issue is the inferface: you don't generally instantiate SchemaGenerator yourself. Tags I can see as a CLI option but security...? (Hence create a subclass for your project may still be needed there.) Let's see what you come up with. Thanks

[dhaval-mehta]

The following approach is just a thought:

Tags are user-defined and vary user to user. On the other hand, security depends on authentication classes.

I am thinking that let authentication classes to provide the schema related methods like paginator classes do(get_paginated_response_schema).

For any custom authentication class, the user/library needs to override those methods.