Improve documentation for customization

The documentation for selective generation of APIs has been updated to
specify the API names are the sanitized UpperCamelCase versions of the
tags in the spec.

The sanitization rules have been documented in a separate section.

Author: cbascom

docs/customization.md

@@ -75,7 +75,7 @@ Excluding `SupportingFiles`, each of the above options may result in multiple fi
 Note that user-defined templates will merge with built-in template definitions. If a supporting file with the sample template file path exists, it will be replaced with the user-defined template, otherwise the user-defined template will be added to the list of template files to compile. If the generator's built-in template is `model_docs.mustache` and you define `model-docs.mustache`, this will result in duplicated model docs (if `destinationFilename` differs) or undefined behavior as whichever template compiles last will overwrite the previous model docs (if `destinationFilename` matches the extension or suffix in the generator's code).
 
 ## Custom Generator (and Template)
- 
+
 <a id="creating-a-new-template"></a> If none of the built-in generators suit your needs and you need to do more than just modify the mustache templates to tweak generated code, you can create a brand new generator and its associated templates. OpenAPI Generator can help with this, using the `meta` command:
 
 ```sh
@@ -95,7 +95,7 @@ To compile your library, enter the `out/generators/my-codegen` directory, run `m
 
 **NOTE** Running your custom generator requires adding it to the classpath. This differs on [Windows](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html) slightly from [unix](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/classpath.html).
 If you are running a Windows Subsystem for Linux or a shell such as gitbash, and have issues with the unix variant, try the Windows syntax below.
- 
+
 Now, execute the generator:
 
 ```sh
@@ -187,13 +187,21 @@ The default is to generate *everything* supported by the specific library. Once
 
 To control the specific files being generated, you can pass a CSV list of what you want:
 ```sh
+# generate the User and Pet APIs only
+--global-property apis="User:Pet"
+
 # generate the User and Pet models only
 --global-property models="User:Pet"
 
 # generate the User model and the supportingFile `StringUtil.java`:
 --global-property models=User,supportingFiles=StringUtil.java
 ```
 
+The names of the apis are the _sanitized_ tags converted to _UpperCamelCase_ and are generated by the following steps:
+- Execute the general [sanitization rules](#sanitization-rules)
+- Prepend the word `Class` if the tag starts with numbers: `123_pet => Class123Pet`
+- Convert the resulting string to upper camel case: `pet_store => PetStore`
+
 To control generation of docs and tests for api and models, pass false to the option. For api, these options are  `--global-property apiTests=false,apiDocs=false`. For models, `--global-property modelTests=false,modelDocs=false`.
 These options default to true and don't limit the generation of the feature options listed above (like `--global-property api`):
 
@@ -447,7 +455,7 @@ will name the API method as `returnPetById` instead of `getPetById` obtained fro
 
 ## Schema Mapping
 
-One can map the schema to something else (e.g. external objects/models outside of the package) using the `schemaMappings` option, e.g. in CLI
+One can map the schema to something else (e.g. external objects/models outside the package) using the `schemaMappings` option, e.g. in CLI
 ```sh
 java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g java -i modules/openapi-generator/src/test/resources/3_0/type-alias.yaml -o /tmp/java2/ --schema-mappings TypeAlias=foo.bar.TypeAlias
 ```
@@ -510,7 +518,7 @@ Another useful option is `inlineSchemaOptions`, which allows you to customize ho
 
 OpenAPI Normalizer transforms the input OpenAPI doc/spec (which may not perfectly conform to the specification) to make it workable with OpenAPI Generator. A few rules are switched on by default since 7.0.0 release:
 
-- SIMPLIFY_ONEOF_ANYOF 
+- SIMPLIFY_ONEOF_ANYOF
 - SIMPLIFY_BOOLEAN_ENUM
 
 (One can use `DISABLE_ALL=true` to disable all the rules)
@@ -607,13 +615,13 @@ The `FILTER` parameter allows selective inclusion of API operations based on spe
 
 ### Available Filters
 
-- **`operationId`**  
+- **`operationId`**
   When set to `operationId:addPet|getPetById`, operations **not** matching `addPet` or `getPetById` will be marked as internal (`x-internal: true`), and excluded from generation. Matching operations will have `x-internal: false`.
 
-- **`method`**  
+- **`method`**
   When set to `method:get|post`, operations **not** using `GET` or `POST` methods will be marked as internal (`x-internal: true`), preventing their generation.
 
-- **`tag`**  
+- **`tag`**
   When set to `tag:person|basic`, operations **not** tagged with `person` or `basic` will be marked as internal (`x-internal: true`), and will not be generated.
 
 ### Example Usage
@@ -670,3 +678,17 @@ Into this securityScheme:
       scheme: bearer
       type: http
 ```
+
+## Sanitization Rules
+
+Various identifiers have to go through a set of sanitization rules to remove invalid characters. This is performed by [DefaultCodeGen#sanitizeName](https://github.com/OpenAPITools/openapi-generator/blob/3ab495a0aa094eb9b1c7a46aea0adca8de8deeb6/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultCodegen.java#L6538C19-L6538C107).
+
+Whenever an identifier is said to be sanitized, the following rules are being performed:
+- Removes any occurrences of the substring `[]`: `input[] => input`
+- Replaces indexing with underscores: `input[a][b] => input_a_b`
+- Replaces parenthesized substrings with underscores: `input(a)(b) => input_a_b`
+- Replaces dots, colons, and hyphens with underscores: `input.name, input:name, input-name => input_name`
+- Replaces pipes with underscores: `a|b => a_b`
+- Replaces spaces with underscores: `input name and age => input_name_and_age`
+- Replaces forward and backward slashes with underscores: `/api/films/get, \api\films\get => _api_films_get`
+- Removes all remaining non-word characters. Unicode characters are allowed if the `allowUnicodeIdentifiers` [config option](https://openapi-generator.tech/docs/configuration/) is true.