Closed xadhoom closed 1 year ago
Hi @xadhoom, thank you for kicking this off. As you can probably tell, most of the operations in my test cases have tags or a long operation ID separated by slashes, so things fall apart for other specs.
First, let's talk about the long term: I don't think this generator can naturally support all of the edge cases that come up with different specs. I'm starting to believe that a plugin system might be necessary, where each step of the code generation has opportunities for library authors to bring their own functions — for example, bring your own function to decide the name of an operation based on a well-defined struct provided by this library.
However, I think we're a little ways off from that. In the meantime, what you've proposed sounds great. Library authors should definitely have control over whether tags are used, and a fallback module name is necessary. Your configuration options seem clear and straightforward to me.
I will add two minor comments on the code (even though it's WIP) but overall I like the direction.
Resolved all points and added some docs, too.
Just a note: English is not my first language so please check if I've not made any big mistake in docs ;)
Rationale:
OpenAPI tags are a nice way to organize operations, but strictly speaking is not part of the API itself. Using tags to generate modules naming is useful, but also can be useful to not use them at all, because operation ids, which are unique, are sufficient.
This PR adds 2 new configs paramenters:
operation_use_tags
: allows to skip usage of tags in module naming, the resulting client will have all operations grouped into a single generated module. The default istrue
.operation_default_module
: When the operation has not tags, or tags are disabled the operation might be without a base module name, which will break client generation. The currentOpenAPI.Generator.Operation.names/1
generates modules names for operation without tags only if the operation itself has a special naming. If this naming is not matched, the operation will have anil
module which results into a failed generation. This option allows to define which module name to use for all operations without a tag, defaulting toDefault
Example: Using
operation_use_tags: true
will generate a<base_module>.Default
module with all operations in it.The PR is still WIP because I want to discuss your opinion, if it can be useful or not. If yes I can properly document it before merging.