From f0a624a135c156c5b79a80dc29f9586a1180446c Mon Sep 17 00:00:00 2001 From: Stefan Koppier Date: Fri, 2 Jun 2023 14:59:18 +0200 Subject: [PATCH] Documentation update (#15728) * 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 --- docs/building.md | 2 +- docs/configuration.md | 14 +-- docs/installation.md | 12 +-- docs/plugins.md | 32 +++---- .../README.adoc | 92 +++++++++---------- 5 files changed, 76 insertions(+), 76 deletions(-) diff --git a/docs/building.md b/docs/building.md index 9e91349812c..948bf40e721 100644 --- a/docs/building.md +++ b/docs/building.md @@ -7,7 +7,7 @@ title: Building the code 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/) diff --git a/docs/configuration.md b/docs/configuration.md index b5590ec21ad..30d95b58f39 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -34,10 +34,10 @@ _How_ you provide values to options also depends on the tool. OpenAPI Generator ``` openApiGenerate { - globalProperties = [ + globalProperties.set([ apis: "", models: "User:Pet" - ] + ]) } ``` @@ -107,12 +107,12 @@ It may seem like a typo but there are two `=` signs in the above example. ``` openApiGenerate { - generatorName = "mysql-schema" - inputSpec = "$rootDir/spec.yaml".toString() - outputDir = "$buildDir/mysql".toString() - configOptions = [ + generatorName.set("mysql-schema") + inputSpec.set("$rootDir/spec.yaml") + outputDir.set("$buildDir/mysql") + configOptions.set([ identifierNamingConvention: "snake_case" - ] + ]) } ``` diff --git a/docs/installation.md b/docs/installation.md index af673a630e3..8609f80af61 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -101,29 +101,29 @@ docker run --rm \ > **Platform(s)**: Linux, macOS, Windows -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: ```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. ```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 ``` 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 -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 ``` diff --git a/docs/plugins.md b/docs/plugins.md index dae527d4048..62e71586e90 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -16,7 +16,7 @@ Add to your `build->plugins` section (default phase is `generate-sources` phase) org.openapitools openapi-generator-maven-plugin - 6.0.0 + 6.6.0 @@ -75,10 +75,10 @@ To include in your project, add the following to `build.gradle`: buildscript { repositories { mavenLocal() - maven { url "https://repo1.maven.org/maven2" } + mavenCentral() } 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: -| Task | Description | -| ---- | ----------- | -| 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. | -| openApiMeta | Generates a new generator to be consumed via Open API Generator. | -| openApiValidate | Validates an Open API 2.0 or 3.x specification document. | +| Task | Description | +|-------------------|---------------------------------------------------------------------------------------------| +| 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. | +| openApiMeta | Generates a new generator to be consumed via Open API Generator. | +| 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.: > ```groovy @@ -107,13 +107,13 @@ An example openApiGenerate task configuration for generating a kotlin client: ```groovy openApiGenerate { - generatorName = "kotlin" - inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString() - outputDir = "$buildDir/generated".toString() - apiPackage = "org.openapi.example.api" - invokerPackage = "org.openapi.example.invoker" - modelPackage = "org.openapi.example.model" - configOptions.putAll([ + generatorName.set("kotlin") + inputSpec.set("$rootDir/specs/petstore-v3.0.yaml") + outputDir.set("$buildDir/generated") + apiPackage.set("org.openapi.example.api") + invokerPackage.set("org.openapi.example.invoker") + modelPackage.set("org.openapi.example.model") + configOptions.set([ dateLibrary: "java8" ]) } diff --git a/modules/openapi-generator-gradle-plugin/README.adoc b/modules/openapi-generator-gradle-plugin/README.adoc index cfc2e2cc3a5..b55c5e8565a 100644 --- a/modules/openapi-generator-gradle-plugin/README.adoc +++ b/modules/openapi-generator-gradle-plugin/README.adoc @@ -44,17 +44,17 @@ All extensions can be rewritten as tasks. Where you can have only a single exten ---- // Validating a single specification openApiValidate { - inputSpec = "$rootDir/petstore-v3.0-invalid.yaml".toString() + inputSpec.set("$rootDir/petstore-v3.0-invalid.yaml") } // Define a task for validating one specification -task validateGoodSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask){ - inputSpec = "$rootDir/petstore-v3.0.yaml".toString() +task validateGoodSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask) { + inputSpec.set("$rootDir/petstore-v3.0.yaml") } // Define a task for validating another specification -task validateBadSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask){ - inputSpec = "$rootDir/petstore-v3.0-invalid.yaml".toString() +task validateBadSpec(type: org.openapitools.generator.gradle.plugin.tasks.ValidateTask) { + inputSpec.set("$rootDir/petstore-v3.0-invalid.yaml") } // 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 [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.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] ---- 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 { repositories { mavenLocal() - maven { url "https://repo1.maven.org/maven2" } + mavenCentral() // or, via Gradle Plugin Portal: // url "https://plugins.gradle.org/m2/" } 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 { // other settings omitted - globalProperties = [ + globalProperties.set([ modelDocs: "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. @@ -446,10 +446,10 @@ When enabling generation of only specific parts you either have to provide CSV l ---- openApiGenerate { // other settings omitted - globalProperties = [ + globalProperties.set([ apis: "", models: "User:Pet" - ] + ]) } ---- ==== @@ -518,15 +518,15 @@ This task exposes all options available via OpenAPI Generator CLI and the OpenAP [source,groovy] ---- openApiGenerate { - generatorName = "kotlin" - inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString() - outputDir = "$buildDir/generated".toString() - apiPackage = "org.openapi.example.api" - invokerPackage = "org.openapi.example.invoker" - modelPackage = "org.openapi.example.model" - configOptions = [ + generatorName.set("kotlin") + inputSpec.set("$rootDir/specs/petstore-v3.0.yaml") + outputDir.set("$buildDir/generated") + apiPackage.set("org.openapi.example.api") + invokerPackage.set("org.openapi.example.invoker") + modelPackage.set("org.openapi.example.model") + configOptions.set([ dateLibrary: "java8" - ] + ]) } ---- @@ -579,8 +579,8 @@ Please run the above task to list all available generators. [source,groovy] ---- openApiMeta { - generatorName = "Jim" - packageName = "us.jimschubert.example" + generatorName.set("Jim") + packageName.set("us.jimschubert.example") } ---- @@ -610,8 +610,8 @@ BUILD SUCCESSFUL in 0s [source,groovy] ---- openApiValidate { - inputSpec = "/src/openapi-generator/modules/openapi-generator/src/test/resources/3_0/petstore.yaml" - recommend = true + inputSpec.set("/src/openapi-generator/modules/openapi-generator/src/test/resources/3_0/petstore.yaml") + 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. ```gradle -task buildGoClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask){ - generatorName = "go" - inputSpec = "$rootDir/petstore-v3.0.yaml".toString() - additionalProperties = [ +task buildGoClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) { + generatorName.set("go") + inputSpec.set("$rootDir/petstore-v3.0.yaml") + additionalProperties.set([ packageName: "petstore" - ] - outputDir = "$buildDir/go".toString() - configOptions = [ + ]) + outputDir.set("$buildDir/go") + configOptions.set([ dateLibrary: "threetenp" - ] + ]) } -task buildKotlinClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask){ - generatorName = "kotlin" - inputSpec = "$rootDir/petstore-v3.0.yaml".toString() - outputDir = "$buildDir/kotlin".toString() - apiPackage = "org.openapitools.example.api" - invokerPackage = "org.openapitools.example.invoker" - modelPackage = "org.openapitools.example.model" - configOptions = [ +task buildKotlinClient(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) { + generatorName.set("kotlin") + inputSpec.set("$rootDir/petstore-v3.0.yaml") + outputDir.set("$buildDir/kotlin") + apiPackage.set("org.openapitools.example.api") + invokerPackage.set("org.openapitools.example.invoker") + modelPackage.set("org.openapitools.example.model") + configOptions.set([ dateLibrary: "java8" - ] - globalProperties = [ + ]) + globalProperties.set([ modelDocs: "false" - ] + ]) } ``` @@ -740,7 +740,7 @@ buildscript { } dependencies { 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' } }