Skip to content
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

Update documentation with global propperty #6863

Merged
merged 4 commits into from
Jul 5, 2020
Merged

Update documentation with global propperty #6863

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0c46efa
update documentation with global propperty
wing328 Jul 5, 2020
fdd121c
remove java opts
wing328 Jul 5, 2020
dd235b2
remove KotlinNewServerCodegen
wing328 Jul 5, 2020
4c2ec97
update contributing.md
wing328 Jul 5, 2020
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
13 changes: 9 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,12 +85,17 @@ For [Vendor Extensions](https://github.com/OAI/OpenAPI-Specification/blob/master
To add test cases (optional) covering the change in the code generator, please refer to [modules/openapi-generator/src/test/java/org/openapitools/codegen](https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/test/java/org/openapitools/codegen)

To test the templates, please perform the following:
- Update the Petstore sample by running the shell scripts under `bin` and `bin/openapi3` folder. For example, run `./bin/python-petstore.sh` and `./bin/openapi3/python-petstore.sh` to update the Python PetStore API client under [`samples/client/petstore/python`](https://github.com/openapitools/openapi-generator/tree/master/samples/client/petstore/python) and [`samples/openapi3/client/petstore/python`](https://github.com/openapitools/openapi-generator/tree/master/samples/openapi3/client/petstore/python). For Windows, the batch files can be found under `bin\windows` folder. (If you find that there are new files generated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI spec from time to time. If you've questions or concerns, please open a ticket to start a discussion)
- During development it can be helpful to quickly regenerate the samples without recompiling all of openapi-generator, e.g. when you have only updated the mustache templates. This can be done by passing the `-t` parameter: `./bin/python-petstore.sh -t modules/openapi-generator/src/main/resources/python`.
- Run the tests in the sample folder using maven `mvn integration-test -rf :<artifactId>`, e.g. open a shell in `samples/client/petstore/python`, run `mvn integration-test -rf :PythonPetstoreClientTests`. The artifactId of the project can be found in the pom.xml file. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests)

- Update the Petstore sample by running the shell scripts under the `bin` folder. For example, run `./bin/generate-samples.sh .
/bin/configs/python*` to update the Python-related samples under [`samples`](https://github.com/openapitools/openapi-generator/t
ree/master/samples). For Windows, please install [GIT bash](https://gitforwindows.org/). (If you find that there are new files g
enerated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI spec fro
m time to time. If you've questions or concerns, please open a ticket to start a discussion)
- During development it can be helpful to quickly regenerate the samples without recompiling all of openapi-generator, e.g. when you have only updated the mustache templates. This can be done by passing the `-t` parameter: `-t modules/openapi-generator/src/main/resources/python`.
- Run the tests in the sample folder using maven `mvn integration-test -f /path/to/pom.xml`, e.g. `mvn integration-test -f samples/client/petstore/python/pom.xml`. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests)
- Finally, git commit the updated samples files: `git commit -a`
(`git add -A` if added files with new test cases)
- For new test cases, please add to the [Fake Petstore spec](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yaml)
- For new test cases, please add to the [Fake Petstore spec](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml)

To start the CI tests, you can:
- Run `mvn verify -Psamples`, assuming you have all the required tools installed to run tests for different languages.
Expand Down
34 changes: 16 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ OpenAPI Generator allows generation of API client libraries (SDK generation), se
- [1.4 - Build Projects](#14---build-projects)
- [1.5 - Homebrew](#15---homebrew)
- [1.6 - Docker](#16---docker)
- [1.7 - NPM](#17---npm)
- [1.7 - NPM](#17---npm)
- [2 - Getting Started](#2---getting-started)
- [3 - Usage](#3---usage)
- [3.1 - Customization](#31---customization)
Expand Down Expand Up @@ -457,29 +457,28 @@ NAME
SYNOPSIS
openapi-generator-cli generate
[(-a <authorization> | --auth <authorization>)]
[--api-name-suffix <api name suffix>]
[--api-package <api package>] [--artifact-id <artifact id>]
[--artifact-version <artifact version>]
[(-c <configuration file> | --config <configuration file>)]
[-D <system properties>...]
[--api-name-suffix <api name suffix>] [--api-package <api package>]
[--artifact-id <artifact id>] [--artifact-version <artifact version>]
[(-c <configuration file> | --config <configuration file>)] [--dry-run]
[(-e <templating engine> | --engine <templating engine>)]
[--enable-post-process-file]
[(-g <generator name> | --generator-name <generator name>)]
[--generate-alias-as-model] [--git-repo-id <git repo id>]
[--git-user-id <git user id>] [--group-id <group id>]
[--generate-alias-as-model] [--git-host <git host>]
[--git-repo-id <git repo id>] [--git-user-id <git user id>]
[--global-property <global properties>...] [--group-id <group id>]
[--http-user-agent <http user agent>]
(-i <spec file> | --input-spec <spec file>)
[(-i <spec file> | --input-spec <spec file>)]
[--ignore-file-override <ignore file override location>]
[--import-mappings <import mappings>...]
[--instantiation-types <instantiation types>...]
[--invoker-package <invoker package>]
[--language-specific-primitives <language specific primitives>...]
[--library <library>] [--log-to-stderr] [--minimal-update]
[--legacy-discriminator-behavior] [--library <library>]
[--log-to-stderr] [--minimal-update]
[--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[--model-package <model package>]
[(-o <output directory> | --output <output directory>)]
[(-p <additional properties> | --additional-properties <additional properties>)...]
[(-o <output directory> | --output <output directory>)] [(-p <additional properties> | --additional-properties <additional properties>)...]
[--package-name <package name>] [--release-note <release note>]
[--remove-operation-id-prefix]
[--reserved-words-mappings <reserved word mappings>...]
Expand Down Expand Up @@ -509,13 +508,12 @@ mvn package
```

Other languages have petstore samples, too:
```sh
./bin/android-petstore-all.sh
./bin/java-petstore-all.sh
./bin/objc-petstore.sh
```

... and others. [Here is a list of all scripts.](https://github.com/OpenAPITools/openapi-generator/wiki/Samples-folder#scripts)
- [Swift5](https://github.com/OpenAPITools/openapi-generator/tree/master/samples/client/petstore/swift5)
- [Ruby](https://github.com/OpenAPITools/openapi-generator/tree/master/samples/client/petstore/ruby)
- [Kotlin](https://github.com/OpenAPITools/openapi-generator/tree/master/samples/client/petstore/kotlin)

... and more.

### [3.1 - Customization](#table-of-contents)

Expand Down
2 changes: 1 addition & 1 deletion docs/building.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Once built, `run-in-docker.sh` will act as an executable for openapi-generator-c
./run-in-docker.sh list # Executes 'list' command for openapi-generator-cli
./run-in-docker.sh /gen/bin/generate-samples.sh /gen/bin/configs/go-petstore.yaml # Builds the Go client
./run-in-docker.sh generate -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
-g go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore
-g go -o /gen/out/go-petstore --packageName=petstore # generates go client, outputs locally to ./out/go-petstore
```

### Docker in Vagrant
Expand Down
13 changes: 9 additions & 4 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,12 +89,17 @@ For [Vendor Extensions](https://github.com/OAI/OpenAPI-Specification/blob/master
To add test cases (optional) covering the change in the code generator, please refer to [modules/openapi-generator/src/test/java/org/openapitools/codegen](https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/test/java/org/openapitools/codegen)

To test the templates, please perform the following:
- Update the Petstore sample by running the shell scripts under `bin` and `bin/openapi3` folder. For example, run `./bin/python-petstore.sh` and `./bin/openapi3/python-petstore.sh` to update the Python PetStore API client under [`samples/client/petstore/python`](https://github.com/openapitools/openapi-generator/tree/master/samples/client/petstore/python) and [`samples/openapi3/client/petstore/python`](https://github.com/openapitools/openapi-generator/tree/master/samples/openapi3/client/petstore/python). For Windows, the batch files can be found under `bin\windows` folder. (If you find that there are new files generated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI spec from time to time. If you've questions or concerns, please open a ticket to start a discussion)
- During development it can be helpful to quickly regenerate the samples without recompiling all of openapi-generator, e.g. when you have only updated the mustache templates. This can be done by passing the `-t` parameter: `./bin/python-petstore.sh -t modules/openapi-generator/src/main/resources/python`.
- Run the tests in the sample folder using maven `mvn integration-test -rf :<artifactId>`, e.g. open a shell in `samples/client/petstore/python`, run `mvn integration-test -rf :PythonPetstoreClientTests`. The artifactId of the project can be found in the pom.xml file. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests)

- Update the Petstore sample by running the shell scripts under the `bin` folder. For example, run `./bin/generate-samples.sh .
/bin/configs/python*` to update the Python-related samples under [`samples`](https://github.com/openapitools/openapi-generator/t
ree/master/samples). For Windows, please install [GIT bash](https://gitforwindows.org/). (If you find that there are new files g
enerated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI spec fro
m time to time. If you've questions or concerns, please open a ticket to start a discussion)
- During development it can be helpful to quickly regenerate the samples without recompiling all of openapi-generator, e.g. when you have only updated the mustache templates. This can be done by passing the `-t` parameter: `-t modules/openapi-generator/src/main/resources/python`.
- Run the tests in the sample folder using maven `mvn integration-test -f /path/to/pom.xml`, e.g. `mvn integration-test -f samples/client/petstore/python/pom.xml`. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests)
- Finally, git commit the updated samples files: `git commit -a`
(`git add -A` if added files with new test cases)
- For new test cases, please add to the [Fake Petstore spec](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yaml)
- For new test cases, please add to the [Fake Petstore spec](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml)

To start the CI tests, you can:
- Run `mvn verify -Psamples`, assuming you have all the required tools installed to run tests for different languages.
Expand Down
36 changes: 15 additions & 21 deletions docs/customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,63 +93,57 @@ If you publish your artifact to a distant maven repository, do not forget to add

You may not want to generate *all* models in your project. Likewise, you may want just one or two apis to be written. If that's the case, you can use system properties or [global properties](./global-properties.md) to control the output.

The default is generate *everything* supported by the specific library. Once you enable a feature, it will restrict the contents generated:
The default is generate *everything* supported by the specific library. Once you enable a feature, it will restrict the contents generated:

```sh
# generate only models
java -Dmodels {opts}
--global-property models
Copy link
Member

Choose a reason for hiding this comment

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

@wing328 this charge isn't correct. The syntax in the README is system properties, and value-less properties like models/APIs can only be passed as system properties like exist in the README.

To change to our CLI args, any occurrence must follow the generate CLI command and must have key=value syntax.

The reason our -D option was removed from CLI is because people mistakenly thought this worked in any position and modified system properties similar to the mvn app. Even I was confused by this when I began contributing.

Copy link
Member Author

Choose a reason for hiding this comment

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

@jimschubert Let's not advertise the usage of -D (any position), shall we? The main reason is what you've pointed out - confusing.


# generate only apis
java -Dapis {opts}
--global-property apis

# generate only supporting files
java -DsupportingFiles
--global-property supportingFiles

# generate models and supporting files
java -Dmodels -DsupportingFiles
--global-property models,supportingFiles
```

To control the specific files being generated, you can pass a CSV list of what you want:
```sh
# generate the User and Pet models only
-Dmodels=User,Pet
--global-property models="User,Pet"

# generate the User model and the supportingFile `StringUtil.java`:
-Dmodels=User -DsupportingFiles=StringUtil.java
--global-property models=User,supportingFiles=StringUtil.java
```

To control generation of docs and tests for api and models, pass false to the option. For api, these options are `-DapiTests=false` and `-DapiDocs=false`. For models, `-DmodelTests=false` and `-DmodelDocs=false`.
These options default to true and don't limit the generation of the feature options listed above (like `-Dapi`):
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`):

```sh
# generate only models (with tests and documentation)
java -Dmodels {opts}
--global-property models

# generate only models (with tests but no documentation)
java -Dmodels -DmodelDocs=false {opts}
--global-property models,modelDocs=false

# generate only User and Pet models (no tests and no documentation)
java -Dmodels=User,Pet -DmodelTests=false {opts}
--global-property models="User,Pet",modelTests=false

# generate only apis (without tests)
java -Dapis -DapiTests=false {opts}
--global-property apis,apiTests=false

# generate only apis (modelTests option is ignored)
java -Dapis -DmodelTests=false {opts}
--global-property apis,modelTests=false
```

When using selective generation, _only_ the templates needed for the specific generation will be used.

To skip models defined as the form parameters in "requestBody", please use `skipFormModel` (default to false) (this option is introduced at v3.2.2)

```sh
java -DskipFormModel=true <path to jar> generate …
```

or

```sh
java <path to jar> generate --global-property skipFormModel=true …
--global-property skipFormModel=true
```

This option will be helpful to skip model generation due to the form parameter, which is defined differently in OAS3 as there's no form parameter in OAS3
Expand Down
Loading