From b888423fd808174c36471197509abac95bc01f21 Mon Sep 17 00:00:00 2001 From: William Cheng Date: Wed, 14 Oct 2020 10:13:17 +0800 Subject: [PATCH] Use 3.0 spec in documentations, update docs (#7710) * update npm set version, use 3_0 spec * use 3_0 spec in website --- README.md | 6 ++++++ docs/building.md | 2 +- docs/customization.md | 6 +++--- docs/faq-generators.md | 4 ++-- docs/file-post-processing.md | 2 +- docs/installation.md | 8 ++++---- docs/integration.md | 2 +- docs/new-generator.md | 2 +- docs/online.md | 10 +++++----- docs/templating.md | 2 +- docs/usage.md | 4 ++-- new.sh | 2 +- website/src/pages/index.js | 10 +++++----- 13 files changed, 33 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index d53b1f9d93..b22b48f02c 100644 --- a/README.md +++ b/README.md @@ -393,6 +393,12 @@ openapi-generator-cli 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 diff --git a/docs/building.md b/docs/building.md index 38de51c222..7806cc42c9 100644 --- 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 ``` diff --git a/docs/customization.md b/docs/customization.md index 050deb2915..dbdfc6634b 100644 --- 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 diff --git a/docs/faq-generators.md b/docs/faq-generators.md index ba2f7ca4f0..7f21a93860 100644 --- 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/ ``` diff --git a/docs/file-post-processing.md b/docs/file-post-processing.md index f4d066d38b..a23845adae 100644 --- 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/ diff --git a/docs/installation.md b/docs/installation.md index 697764a147..3eafc49080 100644 --- 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: ```bash -npm install @openapitools/openapi-generator-cli@cli-4.3.1 -g +openapi-generator-cli version-manager set 4.3.1 ``` 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: diff --git a/docs/integration.md b/docs/integration.md index d53882d959..29495ebfeb 100644 --- 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" \ diff --git a/docs/new-generator.md b/docs/new-generator.md index d440d2a7fd..c4aaab1447 100644 --- 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" diff --git a/docs/online.md b/docs/online.md index 9ae4eb9853..3c86b1acd1 100644 --- 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 ``` diff --git a/docs/templating.md b/docs/templating.md index 25f48524e6..f6ab9bc06b 100644 --- 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: diff --git a/docs/usage.md b/docs/usage.md index ac66a5bbe4..bbeb50ea6b 100644 --- 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 < "${root}/bin/configs/${gen_name_camel}-${gen_type}-petstore-new.yaml"< */}

Then, generate a ruby client from a valid petstore.yaml doc:

{` @@ -175,7 +175,7 @@ const callouts = [

Then, generate a ruby client from a valid petstore.yaml doc:

@@ -193,7 +193,7 @@ const callouts = [ 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 doc + href="https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml">petstore.yaml doc with this image, you'll need to mount a local location as a volume.