Use 3.0 spec in documentations, update docs (#7710)

* update npm set version, use 3_0 spec * use 3_0 spec in website
2020-10-14 10:13:17 +08:00 · 2020-10-14 10:13:17 +08:00 · b888423fd8
commit b888423fd8
parent 6046c3da94
13 changed files with 33 additions and 27 deletions
--- a/README.md
+++ b/README.md
@ -393,6 +393,12 @@ openapi-generator-cli version
 ```

 <!-- RELEASE_VERSION -->
+To use a specific version of "openapi-generator-cli"
+
+```sh
+openapi-generator-cli version-manager set 4.3.1
+```
+
 Or install it as dev-dependency:

 ```sh
--- a/docs/building.md
+++ b/docs/building.md
@ -44,7 +44,7 @@ Once built, `run-in-docker.sh` will act as an executable for openapi-generator-c
 ./run-in-docker.sh help # Executes 'help' command for openapi-generator-cli
 ./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 \
+./run-in-docker.sh generate -i modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
    -g go -o /gen/out/go-petstore --packageName=petstore # generates go client, outputs locally to ./out/go-petstore
 ```

--- a/docs/customization.md
+++ b/docs/customization.md
@ -112,7 +112,7 @@ Note the `my-codegen` is an option for `-g` now, and you can use the usual argum
 ```sh
 java -cp out/codegens/customCodegen/target/my-codegen-openapi-generator-1.0.0.jar:modules/openapi-generator-cli/target/openapi-generator-cli.jar \
  org.openapitools.codegen.OpenAPIGenerator generate -g my-codegen \
-  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
+  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
  -o ./out/myClient
 ```

@ -120,7 +120,7 @@ For Windows users:
 ```
 java -cp "out/codegens/customCodegen/target/my-codegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar" \
  org.openapitools.codegen.OpenAPIGenerator generate -g my-codegen \
-  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
+  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
  -o ./out/myClient
 ```

@ -283,7 +283,7 @@ Each of these files creates reasonable defaults so you can get running quickly.

 ```sh
 java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
+  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
  -g java \
  -o samples/client/petstore/java \
  -c path/to/config.json
--- a/docs/faq-generators.md
+++ b/docs/faq-generators.md
@ -39,7 +39,7 @@ config.templateDir = 'src/openapi-generator-templates/Java/libraries/feign
 ```
 mvn clean package
 java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-  -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.json \
+  -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.json \
  -l java --library=okhttp-gson \
  --additional-properties hideGenerationTimestamp=true \
  -o /var/tmp/java/okhttp-gson/ 
@ -55,7 +55,7 @@ To generate the Android SDK with [`volley`](https://github.com/mcxiaoke/android-
 ```
 mvn clean package
 java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-  -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.json \
+  -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.json \
  -l android --library=volley \
  -o /var/tmp/android/volley/ 
 ```
--- a/docs/file-post-processing.md
+++ b/docs/file-post-processing.md
@ -48,7 +48,7 @@ Let's see how to pass Ruby generated files to Rubocop, a static code analysis/li
 # First, export the required environment variable
 export RUBY_POST_PROCESS_FILE="/usr/local/bin/rubocop -a"

-export OPENAPI_DOC="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
+export OPENAPI_DOC="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"

 # Invoke the generator with --enable-post-process-file
 openapi-generator generate --enable-post-process-file -i $OPENAPI_DOC -g ruby -o .out-ruby/
--- a/docs/installation.md
+++ b/docs/installation.md
@ -22,7 +22,7 @@ npm install @openapitools/openapi-generator-cli -g
 To install a specific version of the tool, pass the version during installation:
 <!-- RELEASE_VERSION -->
 ```bash
-npm install @openapitools/openapi-generator-cli@cli-4.3.1 -g
+openapi-generator-cli version-manager set 4.3.1
 ```
 <!-- /RELEASE_VERSION -->
 To install the tool as a dev dependency in your current project:
@ -30,7 +30,7 @@ To install the tool as a dev dependency in your current project:
 ```bash
 npm install @openapitools/openapi-generator-cli -D
 ```
-Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc:
+Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml) doc:

 ```bash
 npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g ruby -o /tmp/test/
@ -48,7 +48,7 @@ npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g ruby -o /tm
 brew install openapi-generator
 ```

-Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc:
+Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml) doc:

 ```bash
 openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/
@ -60,7 +60,7 @@ openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/

 The OpenAPI Generator Docker image acts as a standalone executable. It can be used as an alternative to installing via homebrew, or for developers who are unable to install Java or upgrade the installed version.

-To generate code from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc with this image, you'll need to mount a local location as a volume.
+To generate code from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml) doc with this image, you'll need to mount a local location as a volume.
 You'll then need to output the generated code to this mapped volume. Everything else works the same as if you ran the command on your host machine.

 Here's an example generating a Go client:
--- a/docs/integration.md
+++ b/docs/integration.md
@ -40,7 +40,7 @@ To push the auto-generated SDK to GitHub, we provide `git_push.sh` to streamline
 2) Generate the SDK
 ```sh
 java -jar openapi-generator-cli.jar generate \
- -i modules/openapi-generator/src/test/resources/2_0/petstore.json -g perl \
+ -i modules/openapi-generator/src/test/resources/3_0/petstore.json -g perl \
 --git-user-id "wing328" \
 --git-repo-id "petstore-perl" \
 --release-note "GitHub integration demo" \
--- a/docs/new-generator.md
+++ b/docs/new-generator.md
@ -334,7 +334,7 @@ The `new.sh` script created the generation config file `bin/configs/common-mark-
 ```bash
 generatorName: common-mark
 outputDir: samples/documentation/petstore/common/mark
-inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore.yaml
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
 templateDir: modules/openapi-generator/src/main/resources/common-mark
 additionalProperties:
  hideGenerationTimestamp: "true"
--- a/docs/online.md
+++ b/docs/online.md
@ -34,7 +34,7 @@ GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}'  ${CID})
 # Execute an HTTP request to generate a Ruby client
 curl -X POST --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
-  -d '{"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \
+  -d '{"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"}' \
  'http://localhost:8888/api/gen/clients/ruby'

 # Example output:
@ -65,7 +65,7 @@ mvn spring-boot:run
 For example, to generate Ruby API client, simply send the following HTTP request using curl:

 ```bash
-curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \
+curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"}' \
    http://localhost:8080/api/gen/clients/ruby
 ```
 Then you will receive a JSON response with the URL to download the zipped code.
@ -75,7 +75,7 @@ To customize the SDK, you can `POST` to `http://localhost:8080/gen/clients/{gene
 ```json
 {
  "options": {},
-  "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
+  "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"
 }
 ```

@ -113,7 +113,7 @@ To set package name to `pet_store`, the HTTP body of the request is as follows:
  "options": {
    "packageName": "pet_store"
  },
-  "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
+  "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"
 }
 ```

@ -121,7 +121,7 @@ and here is the curl command:
 ```bash
 curl -H "Content-type: application/json" \
    -X POST \
-    -d '{"options": {"packageName": "pet_store"},"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \
+    -d '{"options": {"packageName": "pet_store"},"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"}' \
    http://localhost:8080/api/gen/clients/python
 ```

--- a/docs/templating.md
+++ b/docs/templating.md
@ -247,7 +247,7 @@ Now we're ready to generate the client with our simple changes. When we pass the
 openapi-generator generate -g java --library resteasy \
    -t ~/.openapi-generator/templates/Java \
    -o ~/.openapi-generator/example \
-    -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml
+    -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml
 ```

 Make sure your custom template compiles:
--- a/docs/usage.md
+++ b/docs/usage.md
@ -480,7 +480,7 @@ At a minimum, `generate` requires:

 ### Examples

-The following examples use [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml).
+The following examples use [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml).

 #### Additional Properties

@ -649,7 +649,7 @@ Example:
 ```bash
 # create "shared" config
 mkdir shared && cat > shared/common.yaml <<EOF
-inputSpec: https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml
+inputSpec: https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml
 additionalProperties:
    x-ext-name: "Your Name"
 EOF
--- a/new.sh
+++ b/new.sh
@ -204,7 +204,7 @@ echo "Creating bin/configs/${gen_name_camel}-${gen_type}-petstore-new.yaml"
 cat > "${root}/bin/configs/${gen_name_camel}-${gen_type}-petstore-new.yaml"<<EOF
 generatorName: ${gen_name_camel}
 outputDir: samples/${gen_type}/petstore/${gen_name_camel_path}
-inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore.yaml
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
 templateDir: modules/openapi-generator/src/main/resources/${gen_name_camel}
 additionalProperties:
  hideGenerationTimestamp: "true"
--- a/website/src/pages/index.js
+++ b/website/src/pages/index.js
@ -144,8 +144,8 @@ const callouts = [
                   |# install the latest version of "openapi-generator-cli"
                   |npm install @openapitools/openapi-generator-cli -g
                   |
-                   |# install a specific version of "openapi-generator-cli"
-                   |npm install @openapitools/openapi-generator-cli@cli-4.3.1 -g
+                   |# use a specific version of "openapi-generator-cli"
+                   |openapi-generator-cli version-manager set 4.3.1
                   |
                   |# Or install it as dev-dependency in your node.js projects
                   |npm install @openapitools/openapi-generator-cli -D
@ -154,7 +154,7 @@ const callouts = [
                {/*  <!-- /RELEASE_VERSION --> */}

                <p>Then, <strong>generate</strong> a ruby client from a valid <a
-                    href="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
+                    href="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"
                    className="href">petstore.yaml</a> doc:</p>

                <p><CodeBlock className="bash">{`
@ -175,7 +175,7 @@ const callouts = [

                <p>
                    Then, <strong>generate</strong> a ruby client from a valid <a
-                    href="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
+                    href="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"
                    className="href">petstore.yaml</a> doc:
                </p>

@ -193,7 +193,7 @@ const callouts = [
                    installing via homebrew, or for developers who are unable to install Java or upgrade the installed
                    version.</p>
                <p>To generate code from a valid <a
-                    href="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml">petstore.yaml</a> doc
+                    href="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml">petstore.yaml</a> doc
                    with this image, you'll need to mount a local location as a volume.
                </p>
                <p>