Improve documentation for customization

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

The documentation for use of operationIdNameMappings has been updated to
specify that the operationIds have already been sanitized and converted
to lowerCamelCase before they are compared with the specified
operationIdNameMappings.

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_. The sanitization and camelization process performs the following steps:
+- Follows the general [sanitization rules](#sanitization-rules)
+- Prepends the word `Class` if the tag starts with numbers: `123_pet => Class123Pet`
+- Converts 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`):
 
@@ -445,9 +453,27 @@ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generat
 ```
 will name the API method as `returnPetById` instead of `getPetById` obtained from OpenAPI doc/spec.
 
+The `operationId` has had some transformations performed on it prior to being looked up in the operation id name mappings. The following transformations have been performed:
+- If the operationId is blank, the path is used to generate an operationId as follows:
+  - If the path is just the root path (/), it is replaced with the word `root`: `/ => root`
+  - All curly braces for path template parameters are removed: `/pets/{pet-name} => /pets/pet-name`
+  - The HTTP method is appended to the path: `/pets/pet-name/get`
+  - The resulting string is split on `/`
+  - The parts are joined together to form a lowerCamelCase string: `/pets/pet-name/get => petsPet-nameGet`
+  - The resulting operationId has the general [sanitization rules](#sanitization-rules) applied: `petsPet-nameGet => petsPetNameGet`
+- If the operationId is not blank, it is used unmodified
+- If the `removeOperationIdPrefix` [config option](https://openapi-generator.tech/docs/configuration/) is true:
+  - The operationId is split on the `removeOperationIdPrefixDelimiter` character (default: `_`)
+  - The `removeOperationIdPrefixCount` parts are discarded (default: `1`)
+  - The remaining parts are joined using `removeOperationIdPrefixDelimiter`: `data_pets_get => pets_get`
+- The `removeOperationIdPrefixDelimiter` and the `-_:;#` characters are removed after capitalizing the subsequent character
+- The first character is converted to lowercase to yield a lowerCamcelCase operationId
+
+The lowerCamelCase operationId generated from the above transformations is the value that must be configured as the key in the operationIdNameMappings.
+
 ## 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 +672,15 @@ 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. 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.