Request: Improve Tag Naming for Better Code Generation Support #178
Description
Issue: Tag names in api-spec-v2.yaml are not compatible with C# client generation tools like NSwag
Is this a bug report or a feature request?
Bug Report / Spec Improvement
Describe the bug
When using the OpenAPI specification (api-spec-v2.yaml) with code generation tools like NSwag to create C# API clients, the process fails if using a tag-based client generation strategy.
The operationGenerationMode: MultipleClientsFromFirstTagAndOperationId setting in NSwag uses the name from the tags section to create client class names. Several tags in the specification contain parentheses and &, which are invalid characters for C# class names.
Examples of problematic tags:
Policy Editor (Beta)
Blockchains & Assets (Beta)
Keys (Beta)
Webhooks V2 (Beta)
This results in uncompilable C# code with invalid names like Keys_(Beta)Client.
To Reproduce
Configure NSwag to generate a C# client from api-spec-v2.yaml.
Set the operationGenerationMode to MultipleClientsFromFirstTagAndOperationId.
Run the generation tool.
Observe that the generated C# file contains invalid class names and will not compile.
Expected behavior
The tag names in the OpenAPI specification should be sanitized to not include characters that are incompatible with common code generation tools, allowing for the creation of valid, descriptive client classes based on API tags.
Suggested Solution
Sanitize the name property of the tags to remove parentheses. The description field can retain the full, human-readable name.
Proposed Changes:
name: Policy Editor (Beta) -> name: PolicyEditorBeta
name: Blockchains & Assets (Beta) -> name: BlockchainsAssetsBeta
name: Keys (Beta) -> name: KeysBeta
name: Payments - Payout -> name: PaymentsPayout
This change would make the specification much friendlier for automated client generation while preserving the descriptive nature of the tags. While it is possible to use an alternative strategy like MultipleClientsFromPathSegments, the tag-based approach often yields more functionally descriptive client names, which is highly desirable.