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

@@ -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
 ```
@@ -646,3 +654,17 @@ Example:
 ```
 java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g java -i modules/openapi-generator/src/test/resources/3_1/java/petstore.yaml -o /tmp/java-okhttp/ --openapi-normalizer FIX_DUPLICATED_OPERATIONID=true
 ```
+
+## 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.