Skip to content

Improve documentation for customization #20841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cbascom wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve documentation for customization #20841

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions docs/customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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:
Copy link
Member

@wing328 wing328 Mar 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shall we mention it's not always upper camel case and it really depends on the generators (e.g. python uses snake case) ?

Copy link
Contributor Author

@cbascom cbascom Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will have to dig into this since I am still missing a piece somewhere apparently. Will try to take a look again this weekend.

- 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`):

Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Loading