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.