From 51dbc1ff670d81598d9591d121b5ff08c5dee3fc Mon Sep 17 00:00:00 2001 From: Calvin Bascom Date: Mon, 10 Mar 2025 21:46:54 -0400 Subject: [PATCH] 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. --- docs/customization.md | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/docs/customization.md b/docs/customization.md index c4c36bf782fd..e40d5b2c8af0 100644 --- a/docs/customization.md +++ b/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) - + 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,6 +187,9 @@ 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" @@ -194,6 +197,11 @@ To control the specific files being generated, you can pass a CSV list of what y --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.