loafle/openapi-generator-original
3
0
Fork 1
mirror of https://github.com/OpenAPITools/openapi-generator.git synced 2025-05-12 20:50:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation update (#15728)

Browse Source 
* Updated Gradle documentation examples to use correct non-deprecated .set(x) syntax instead of directly assigning

* Updated more Gradle documentation examples to use correct non-deprecated .set(x) syntax instead of directly assigning

* Updated documentation to use Java 11 instead of Java 8
This commit is contained in:
Stefan Koppier 2023-06-02 14:59:18 +02:00 committed by GitHub
parent 421bcd1787
commit f0a624a135
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 76 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/building.md
View File

@ -7,7 +7,7 @@ title: Building the code
To build from source, you need the following installed and available in your `$PATH:` To build from source, you need the following installed and available in your `$PATH:`
* [Java 8](https://java.oracle.com) * [Java 11](https://java.oracle.com)
* [Apache maven 3.3.4 or greater](https://maven.apache.org/) * [Apache maven 3.3.4 or greater](https://maven.apache.org/)

14
docs/configuration.md
View File

@ -34,10 +34,10 @@ _How_ you provide values to options also depends on the tool. OpenAPI Generator
``` ```
openApiGenerate { openApiGenerate {
globalProperties = [ globalProperties.set([
apis: "", apis: "",
models: "User:Pet" models: "User:Pet"
] ])
} }
``` ```
@ -107,12 +107,12 @@ It may seem like a typo but there are two `=` signs in the above example.
``` ```
openApiGenerate { openApiGenerate {
generatorName = "mysql-schema" generatorName.set("mysql-schema")
inputSpec = "$rootDir/spec.yaml".toString() inputSpec.set("$rootDir/spec.yaml")
outputDir = "$buildDir/mysql".toString() outputDir.set("$buildDir/mysql")
configOptions = [ configOptions.set([
identifierNamingConvention: "snake_case" identifierNamingConvention: "snake_case"
] ])
} }
``` ```

12
docs/installation.md
View File

@ -101,29 +101,29 @@ docker run --rm \
> **Platform(s)**: Linux, macOS, Windows > **Platform(s)**: Linux, macOS, Windows
<!-- RELEASE_VERSION --> <!-- RELEASE_VERSION -->
If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 8 runtime at a minimum): If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 11 runtime at a minimum):
JAR location: `https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.3.0/openapi-generator-cli-6.3.0.jar` JAR location: `https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.6.0/openapi-generator-cli-6.6.0.jar`
For **Mac/Linux** users: For **Mac/Linux** users:
```bash ```bash
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.3.0/openapi-generator-cli-6.3.0.jar -O openapi-generator-cli.jar wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.6.0/openapi-generator-cli-6.6.0.jar -O openapi-generator-cli.jar
``` ```
For **Windows** users, you will need to install [wget](http://gnuwin32.sourceforge.net/packages/wget.htm) or you can use Invoke-WebRequest in PowerShell (3.0+), e.g. For **Windows** users, you will need to install [wget](http://gnuwin32.sourceforge.net/packages/wget.htm) or you can use Invoke-WebRequest in PowerShell (3.0+), e.g.
```powershell ```powershell
Invoke-WebRequest -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.3.0/openapi-generator-cli-6.3.0.jar Invoke-WebRequest -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.6.0/openapi-generator-cli-6.6.0.jar
``` ```
<!-- /RELEASE_VERSION --> <!-- /RELEASE_VERSION -->
After downloading the JAR, run `java -jar openapi-generator-cli.jar help` to show the usage. After downloading the JAR, run `java -jar openapi-generator-cli.jar help` to show the usage.
For Mac users, please make sure Java 8 is installed (Tips: run `java -version` to check the version), and export `JAVA_HOME` in order to use the supported Java version: For Mac users, please make sure Java 11 is installed (Tips: run `java -version` to check the version), and export `JAVA_HOME` in order to use the supported Java version:
```bash ```bash
export JAVA_HOME=`/usr/libexec/java_home -v 1.8` export JAVA_HOME=`/usr/libexec/java_home -v 1.11`
export PATH=${JAVA_HOME}/bin:$PATH export PATH=${JAVA_HOME}/bin:$PATH
``` ```

32
docs/plugins.md
View File

@ -16,7 +16,7 @@ Add to your `build->plugins` section (default phase is `generate-sources` phase)
<groupId>org.openapitools</groupId> <groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId> <artifactId>openapi-generator-maven-plugin</artifactId>
<!-- RELEASE_VERSION --> <!-- RELEASE_VERSION -->
<version>6.0.0</version> <version>6.6.0</version>
<!-- /RELEASE_VERSION --> <!-- /RELEASE_VERSION -->
<executions> <executions>
<execution> <execution>
@ -75,10 +75,10 @@ To include in your project, add the following to `build.gradle`:
buildscript { buildscript {
repositories { repositories {
mavenLocal() mavenLocal()
maven { url "https://repo1.maven.org/maven2" } mavenCentral()
} }
dependencies { dependencies {
classpath "org.openapitools:openapi-generator-gradle-plugin:5.0.0" classpath "org.openapitools:openapi-generator-gradle-plugin:6.6.0"
} }
} }
@ -87,12 +87,12 @@ apply plugin: 'org.openapi.generator'
This gives access to the following tasks: This gives access to the following tasks:
| Task | Description | | Task | Description |
| ---- | ----------- | |-------------------|---------------------------------------------------------------------------------------------|
| openApiGenerate | Generate code via Open API Tools Generator for Open API 2.0 or 3.x specification documents. | | openApiGenerate | Generate code via Open API Tools Generator for Open API 2.0 or 3.x specification documents. |
| openApiGenerators | Lists generators available via Open API Generators. | | openApiGenerators | Lists generators available via Open API Generators. |
| openApiMeta | Generates a new generator to be consumed via Open API Generator. | | openApiMeta | Generates a new generator to be consumed via Open API Generator. |
| openApiValidate | Validates an Open API 2.0 or 3.x specification document. | | openApiValidate | Validates an Open API 2.0 or 3.x specification document. |
> The plugin implements the above tasks as project extensions of the same name. If you’d like to declare these tasks as dependencies to other tasks (using `dependsOn`), you’ll need a task reference. e.g.: > The plugin implements the above tasks as project extensions of the same name. If you’d like to declare these tasks as dependencies to other tasks (using `dependsOn`), you’ll need a task reference. e.g.:
> ```groovy > ```groovy
@ -107,13 +107,13 @@ An example openApiGenerate task configuration for generating a kotlin client:
```groovy ```groovy
openApiGenerate { openApiGenerate {
generatorName = "kotlin" generatorName.set("kotlin")
inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString() inputSpec.set("$rootDir/specs/petstore-v3.0.yaml")
outputDir = "$buildDir/generated".toString() outputDir.set("$buildDir/generated")
apiPackage = "org.openapi.example.api" apiPackage.set("org.openapi.example.api")
invokerPackage = "org.openapi.example.invoker" invokerPackage.set("org.openapi.example.invoker")
modelPackage = "org.openapi.example.model" modelPackage.set("org.openapi.example.model")
configOptions.putAll([ configOptions.set([
dateLibrary: "java8" dateLibrary: "java8"
]) ])
} }

92
modules/openapi-generator-gradle-plugin/README.adoc
View File

@ -44,17 +44,17 @@ All extensions can be rewritten as tasks. Where you can have only a single exten
---- ----
// Validating a single specification // Validating a single specification
openApiValidate { openApiValidate {
inputSpec = "$rootDir/petstore-v3.0-invalid.yaml".toString() inputSpec.set("$rootDir/petstore-v3.0-invalid.yaml")
} }
// Define a task for validating one specification // Define a task for validating one specification
task validateGoodSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask){ task validateGoodSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask) {
inputSpec = "$rootDir/petstore-v3.0.yaml".toString() inputSpec.set("$rootDir/petstore-v3.0.yaml")
} }
// Define a task for validating another specification // Define a task for validating another specification
task validateBadSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask){ task validateBadSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask) {
inputSpec = "$rootDir/petstore-v3.0-invalid.yaml".toString() inputSpec.set("$rootDir/petstore-v3.0-invalid.yaml")
} }
// Define a task for batch validations // Define a task for batch validations
@ -81,11 +81,11 @@ Disable up-to-date checks and caching for a custom task:
.Disable caching for custom task .Disable caching for custom task
[source,groovy] [source,groovy]
---- ----
task validateGoodSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask){ task validateGoodSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask) {
outputs.upToDateWhen { false } outputs.upToDateWhen { false }
outputs.cacheIf { false } outputs.cacheIf { false }
inputSpec = "$rootDir/petstore-v3.0.yaml".toString() inputSpec.set("$rootDir/petstore-v3.0.yaml")
} }
---- ----
==== ====
@ -97,7 +97,7 @@ task validateGoodSpec(type: org.openapitools.generator.gradle.plugin.tasks.Valid
[source,group] [source,group]
---- ----
plugins { plugins {
id "org.openapi.generator" version "6.3.0" id "org.openapi.generator" version "6.6.0"
} }
---- ----
@ -108,12 +108,12 @@ Using https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_appl
buildscript { buildscript {
repositories { repositories {
mavenLocal() mavenLocal()
maven { url "https://repo1.maven.org/maven2" } mavenCentral()
// or, via Gradle Plugin Portal: // or, via Gradle Plugin Portal:
// url "https://plugins.gradle.org/m2/" // url "https://plugins.gradle.org/m2/"
} }
dependencies { dependencies {
classpath "org.openapitools:openapi-generator-gradle-plugin:6.3.0" classpath "org.openapitools:openapi-generator-gradle-plugin:6.6.0"
} }
} }
@ -435,10 +435,10 @@ When configuring `globalProperties` in order to perform selective generation you
---- ----
openApiGenerate { openApiGenerate {
// other settings omitted // other settings omitted
globalProperties = [ globalProperties.set([
modelDocs: "false", modelDocs: "false",
apis: "false" apis: "false"
] ])
} }
---- ----
When enabling generation of only specific parts you either have to provide CSV list of what you particularly are generating or provide an empty string `""` to generate everything. If you provide `"true"` it will be treated as a specific name of model or api you want to generate. When enabling generation of only specific parts you either have to provide CSV list of what you particularly are generating or provide an empty string `""` to generate everything. If you provide `"true"` it will be treated as a specific name of model or api you want to generate.
@ -446,10 +446,10 @@ When enabling generation of only specific parts you either have to provide CSV l
---- ----
openApiGenerate { openApiGenerate {
// other settings omitted // other settings omitted
globalProperties = [ globalProperties.set([
apis: "", apis: "",
models: "User:Pet" models: "User:Pet"
] ])
} }
---- ----
==== ====
@ -518,15 +518,15 @@ This task exposes all options available via OpenAPI Generator CLI and the OpenAP
[source,groovy] [source,groovy]
---- ----
openApiGenerate { openApiGenerate {
generatorName = "kotlin" generatorName.set("kotlin")
inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString() inputSpec.set("$rootDir/specs/petstore-v3.0.yaml")
outputDir = "$buildDir/generated".toString() outputDir.set("$buildDir/generated")
apiPackage = "org.openapi.example.api" apiPackage.set("org.openapi.example.api")
invokerPackage = "org.openapi.example.invoker" invokerPackage.set("org.openapi.example.invoker")
modelPackage = "org.openapi.example.model" modelPackage.set("org.openapi.example.model")
configOptions = [ configOptions.set([
dateLibrary: "java8" dateLibrary: "java8"
] ])
} }
---- ----
@ -579,8 +579,8 @@ Please run the above task to list all available generators.
[source,groovy] [source,groovy]
---- ----
openApiMeta { openApiMeta {
generatorName = "Jim" generatorName.set("Jim")
packageName = "us.jimschubert.example" packageName.set("us.jimschubert.example")
} }
---- ----
@ -610,8 +610,8 @@ BUILD SUCCESSFUL in 0s
[source,groovy] [source,groovy]
---- ----
openApiValidate { openApiValidate {
inputSpec = "/src/openapi-generator/modules/openapi-generator/src/test/resources/3_0/petstore.yaml" inputSpec.set("/src/openapi-generator/modules/openapi-generator/src/test/resources/3_0/petstore.yaml")
recommend = true recommend.set(true)
} }
---- ----
@ -669,30 +669,30 @@ Examples can be found in https://github.com/OpenAPITools/openapi-generator/blob/
You can define any number of generator tasks; the generated code does _not_ need to be a JVM language. You can define any number of generator tasks; the generated code does _not_ need to be a JVM language.
```gradle ```gradle
task buildGoClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask){ task buildGoClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
generatorName = "go" generatorName.set("go")
inputSpec = "$rootDir/petstore-v3.0.yaml".toString() inputSpec.set("$rootDir/petstore-v3.0.yaml")
additionalProperties = [ additionalProperties.set([
packageName: "petstore" packageName: "petstore"
] ])
outputDir = "$buildDir/go".toString() outputDir.set("$buildDir/go")
configOptions = [ configOptions.set([
dateLibrary: "threetenp" dateLibrary: "threetenp"
] ])
} }
task buildKotlinClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask){ task buildKotlinClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
generatorName = "kotlin" generatorName.set("kotlin")
inputSpec = "$rootDir/petstore-v3.0.yaml".toString() inputSpec.set("$rootDir/petstore-v3.0.yaml")
outputDir = "$buildDir/kotlin".toString() outputDir.set("$buildDir/kotlin")
apiPackage = "org.openapitools.example.api" apiPackage.set("org.openapitools.example.api")
invokerPackage = "org.openapitools.example.invoker" invokerPackage.set("org.openapitools.example.invoker")
modelPackage = "org.openapitools.example.model" modelPackage.set("org.openapitools.example.model")
configOptions = [ configOptions.set([
dateLibrary: "java8" dateLibrary: "java8"
] ])
globalProperties = [ globalProperties.set([
modelDocs: "false" modelDocs: "false"
] ])
} }
``` ```
@ -740,7 +740,7 @@ buildscript {
} }
dependencies { dependencies {
classpath 'com.android.tools.build:gradle:3.2.1' classpath 'com.android.tools.build:gradle:3.2.1'
classpath('org.openapitools:openapi-generator-gradle-plugin:6.3.0') { classpath('org.openapitools:openapi-generator-gradle-plugin:6.6.0') {
exclude group: 'com.google.guava' exclude group: 'com.google.guava'
} }
} }