From 6af332431daea2660dc70329aa77e45bda8a756b Mon Sep 17 00:00:00 2001 From: lnash94 Date: Thu, 2 May 2024 22:28:32 +0530 Subject: [PATCH 1/6] Update learn page with openAPI changes --- swan-lake/integration-tools/openapi-tool.md | 63 +++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index c961bbc938b..81e1f0469a8 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -32,6 +32,7 @@ $ bal openapi [-i | --input] [-n | --nullable] [--license] [--with-tests] + [--status-code-binding] ``` ### Ballerina to OpenAPI usage @@ -63,6 +64,7 @@ The command-line arguments below can be used with the command for each particula | `-n \|--nullable` | If your OpenAPI specification includes JSON schema properties that are not marked as `nullable:true`, they may return as null in some responses. It results in a JSON schema to Ballerina record data binding error. If you suspect this can happen for any property, it is safe to generate all data types in the generated record with Ballerina nil support by turning on this flag.

**E.g.,** `bal openapi -i [-n \|--nullable]` | Optional | | `--with-tests` | It works with the client generation command and generates a boiler-plate test for all the remote methods of the generated client. | Optional | | `--client-methods`| This option can be used in the client generation to select the client method type, which can be `resource` or `remote`. (The default option is `resource`). | Optional | +| `--status-code-binding`| This option can be used in the client generation to generate the client methods with status code response binding. | Optional | ### Ballerina to OpenAPI command options @@ -285,6 +287,67 @@ $ bal openapi -i --mode client --client-methods **Info:** For more command options, see [OpenAPI to Ballerina CLI options](#openapi-to-ballerina-command-options). +### Automate client generation with Package Build + +#### Update the Ballerina.toml file with OpenAPI tool configurations +Adding the following OpenAPI tool configurations to the Ballerina.toml file will generate a client during the `bal build`. This eliminates the need to commit the generated code. + +> **Info:** It is mandatory to provide `id`,` filePath`, and `targetModule` attributes for the OpenAPI tool configurations. The other attributes are optional. + +The following is an example of the tool configuration usage in the Ballerina.toml. + +```ballerina +[[tool.openapi]] +id = "client01" +filePath = "./openapi.yaml" +targetModule = "delivery01" +options.mode = "client" +options.statusCodeBinding = true +options.tags = ["tag1", "tag2"] +options.operations = ["op1", "op2"] +options.nullable = true # (default value => false) +options.license = "./license.txt" +``` + +The below tool configuration can be used + +| Command option | Description | Mandatory/Optional | +|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| +| `filePath` | The `filePath` tool option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | +| `targetModule` | The Ballerina files are generated at the given directory name in the Ballerina package. | Mandatory | +| `options.mode` | Mode type can be either a service or client. The Ballerina service and client are generated according to the mode. Without the `options.mode`, it generates client stubs for the given OpenAPI contract. | Optional | +| `options.tags` | To generate the Ballerina client or service stub with a subset of tags defined in the OpenAPI contract | Optional | +| `options.operations` | To generate the Ballerina client or service stub with a subset of operations defined in the OpenAPI contract, use the `options.operations` option and specify the operations you need as specified in the OpenAPI definition. | Optional | +| `options.license` | To generate the Ballerina files with the given copyright or license header, you can use this `options.license` option with your copyright text. | Optional | +| `options.nullable` | If your OpenAPI specification includes JSON schema properties that are not marked as `options.nullable=true`, they may return as null in some responses. It results in a JSON schema to Ballerina record data binding error. If you suspect this can happen for any property, it is safe to generate all data types in the generated record with Ballerina nil support by turning on this flag. | Optional | +| `options.clientMethods`| This option can be used in the client generation to select the client method type, which can be `resource` or `remote`. (The default option is `resource`). | Optional | +| `options.statusCodeBinding`| This option can be used in the client generation to generate the client methods with status code response binding. | Optional | + + +#### Update the Ballerina.toml file with OpenAPI CLI command + +Executing the following OpenAPI `add` sub-command, along with the OpenAPI to Ballerina CLI options, will update the Ballerina.toml with OpenAPI tool configurations. +``` +$ bal openapi add [-i | --input] + [--id] + [--module] + [--package] +``` + +Example: +``` +$ bal openapi add -i --id "client_id" --module --package --tags <"tag1","tag2"> +``` +| Command option | Description | Mandatory/Optional | +|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| +| `-i \| --input` | The `openapi-contract-path` command option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | +| `--id` | Id for the generation module | Mandatory | +| `--module` | Module name for the generated client/service stub module (defualt will be generated diractory)| Optional | +| `--package` | The Ballerina package location to generate the Ballerina client or service stub. | Optional | + +>**Info:** For more command options, see [OpenAPI to Ballerina CLI options](#openapi-to-ballerina-command-options). + +``` ## Publish your client To see your new client in Ballerina central in the future, follow the steps below to send a GitHub Pull Request to the WSO2 `openapi-connectors` repository to publish it. From 8ec86e6f926621b6a6e5eca5a2fa52117905a20b Mon Sep 17 00:00:00 2001 From: lnash94 Date: Thu, 2 May 2024 22:46:15 +0530 Subject: [PATCH 2/6] Remove service from mode. --- swan-lake/integration-tools/openapi-tool.md | 29 ++++++++++++--------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index 81e1f0469a8..544f4d0258b 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -220,7 +220,7 @@ import ballerina/openapi; contract: "/path/to/openapi.json|yaml", tags: ["store"], operations: ["op1", "op2"], - failOnErrors: true // (default value => true), + failOnErrors: true # (default value => true), excludeTags: ["pets", "user"], excludeOperations: ["op1", "op2"] } @@ -290,6 +290,7 @@ $ bal openapi -i --mode client --client-methods **Info:** It is mandatory to provide `id`,` filePath`, and `targetModule` attributes for the OpenAPI tool configurations. The other attributes are optional. @@ -300,7 +301,7 @@ The following is an example of the tool configuration usage in the Ballerina.tom [[tool.openapi]] id = "client01" filePath = "./openapi.yaml" -targetModule = "delivery01" +targetModule = "delivery" options.mode = "client" options.statusCodeBinding = true options.tags = ["tag1", "tag2"] @@ -315,18 +316,19 @@ The below tool configuration can be used |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| | `filePath` | The `filePath` tool option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | | `targetModule` | The Ballerina files are generated at the given directory name in the Ballerina package. | Mandatory | -| `options.mode` | Mode type can be either a service or client. The Ballerina service and client are generated according to the mode. Without the `options.mode`, it generates client stubs for the given OpenAPI contract. | Optional | -| `options.tags` | To generate the Ballerina client or service stub with a subset of tags defined in the OpenAPI contract | Optional | -| `options.operations` | To generate the Ballerina client or service stub with a subset of operations defined in the OpenAPI contract, use the `options.operations` option and specify the operations you need as specified in the OpenAPI definition. | Optional | -| `options.license` | To generate the Ballerina files with the given copyright or license header, you can use this `options.license` option with your copyright text. | Optional | +| `options.mode` | Mode type can be client. It generates client stubs for the given OpenAPI contract. | Optional | +| `options.tags` | To generate the Ballerina client stub with a subset of tags defined in the OpenAPI contract | Optional | +| `options.operations` | To generate the Ballerina client stub with a subset of operations defined in the OpenAPI contract, use the `options.operations` option and specify the operations you need as specified in the OpenAPI definition. | Optional | +| `options.license` | To generate the Ballerina files with the given copyright or license header, you can use this `options.license` option with path to your copyright text. | Optional | | `options.nullable` | If your OpenAPI specification includes JSON schema properties that are not marked as `options.nullable=true`, they may return as null in some responses. It results in a JSON schema to Ballerina record data binding error. If you suspect this can happen for any property, it is safe to generate all data types in the generated record with Ballerina nil support by turning on this flag. | Optional | | `options.clientMethods`| This option can be used in the client generation to select the client method type, which can be `resource` or `remote`. (The default option is `resource`). | Optional | | `options.statusCodeBinding`| This option can be used in the client generation to generate the client methods with status code response binding. | Optional | -#### Update the Ballerina.toml file with OpenAPI CLI command +#### Update the Ballerina.toml file with OpenAPI tool configurations using OpenAPI CLI command Executing the following OpenAPI `add` sub-command, along with the OpenAPI to Ballerina CLI options, will update the Ballerina.toml with OpenAPI tool configurations. + ``` $ bal openapi add [-i | --input] [--id] @@ -334,20 +336,21 @@ $ bal openapi add [-i | --input] [--package] ``` -Example: +For example, + ``` -$ bal openapi add -i --id "client_id" --module --package --tags <"tag1","tag2"> +$ bal openapi add -i --id --module --package --tags <"tag1","tag2"> ``` + | Command option | Description | Mandatory/Optional | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| -| `-i \| --input` | The `openapi-contract-path` command option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | +| `-i \| --input` | The `-i|--input` command option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | | `--id` | Id for the generation module | Mandatory | -| `--module` | Module name for the generated client/service stub module (defualt will be generated diractory)| Optional | -| `--package` | The Ballerina package location to generate the Ballerina client or service stub. | Optional | +| `--module` | Module name for the generated client stub module (defualt will be generated diractory)| Optional | +| `-p \|--package` | The Ballerina package location to generate the Ballerina client or service stub. | Optional | >**Info:** For more command options, see [OpenAPI to Ballerina CLI options](#openapi-to-ballerina-command-options). -``` ## Publish your client To see your new client in Ballerina central in the future, follow the steps below to send a GitHub Pull Request to the WSO2 `openapi-connectors` repository to publish it. From 6270279a221ff465219da23f94b8d1580c19c527 Mon Sep 17 00:00:00 2001 From: lnash94 Date: Fri, 3 May 2024 10:05:49 +0530 Subject: [PATCH 3/6] Fix review suggestion --- swan-lake/integration-tools/openapi-tool.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index 544f4d0258b..01ce536635b 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -289,13 +289,13 @@ $ bal openapi -i --mode client --client-methods **Info:** It is mandatory to provide `id`,` filePath`, and `targetModule` attributes for the OpenAPI tool configurations. The other attributes are optional. +> **Info:** It is mandatory to provide `id`, and ` filePath` attributes for the OpenAPI tool configurations. The other attributes are optional. -The following is an example of the tool configuration usage in the Ballerina.toml. +The following is an example of the tool configuration usage in the `Ballerina.toml`. ```ballerina [[tool.openapi]] @@ -315,7 +315,8 @@ The below tool configuration can be used | Command option | Description | Mandatory/Optional | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| | `filePath` | The `filePath` tool option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | -| `targetModule` | The Ballerina files are generated at the given directory name in the Ballerina package. | Mandatory | +| `id` | Id for the generation module | Mandatory | +| `targetModule` | The Ballerina files are generated at the given directory name in the Ballerina package. | Optional | | `options.mode` | Mode type can be client. It generates client stubs for the given OpenAPI contract. | Optional | | `options.tags` | To generate the Ballerina client stub with a subset of tags defined in the OpenAPI contract | Optional | | `options.operations` | To generate the Ballerina client stub with a subset of operations defined in the OpenAPI contract, use the `options.operations` option and specify the operations you need as specified in the OpenAPI definition. | Optional | @@ -327,7 +328,7 @@ The below tool configuration can be used #### Update the Ballerina.toml file with OpenAPI tool configurations using OpenAPI CLI command -Executing the following OpenAPI `add` sub-command, along with the OpenAPI to Ballerina CLI options, will update the Ballerina.toml with OpenAPI tool configurations. +Executing the following OpenAPI `add` sub-command, along with the OpenAPI to Ballerina CLI options, will update the `Ballerina.toml` with OpenAPI tool configurations. ``` $ bal openapi add [-i | --input] From 7283ec5b2467093ef3c4a6c9c42875f39bc803ae Mon Sep 17 00:00:00 2001 From: lnash94 Date: Sat, 4 May 2024 12:47:26 +0530 Subject: [PATCH 4/6] Change the title --- swan-lake/integration-tools/openapi-tool.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index 01ce536635b..3ad977d4122 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -287,11 +287,11 @@ $ bal openapi -i --mode client --client-methods **Info:** For more command options, see [OpenAPI to Ballerina CLI options](#openapi-to-ballerina-command-options). -### Automate client generation with Package Build +### Automate client generation #### Update the `Ballerina.toml` file with OpenAPI tool configurations -Adding the following OpenAPI tool configurations to the `Ballerina.toml` file will generate a client during the `bal build`. This eliminates the need to commit the generated code. +Adding the following OpenAPI tool configurations to the `Ballerina.toml` file will generate a client during the package build. This eliminates the need to commit the generated code. > **Info:** It is mandatory to provide `id`, and ` filePath` attributes for the OpenAPI tool configurations. The other attributes are optional. From 18a6227324af81f51a6104975467eda60dd1cb58 Mon Sep 17 00:00:00 2001 From: lnash94 Date: Sat, 4 May 2024 16:07:44 +0530 Subject: [PATCH 5/6] Fix review suggestions --- swan-lake/integration-tools/openapi-tool.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index 3ad977d4122..5966d138ce5 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -293,7 +293,7 @@ $ bal openapi -i --mode client --client-methods **Info:** It is mandatory to provide `id`, and ` filePath` attributes for the OpenAPI tool configurations. The other attributes are optional. +> **Info:** It is mandatory to provide `id` and `filePath` attributes for the OpenAPI tool configurations. The other attributes are optional. The following is an example of the tool configuration usage in the `Ballerina.toml`. @@ -310,17 +310,17 @@ options.nullable = true # (default value => false) options.license = "./license.txt" ``` -The below tool configuration can be used +The below tool configuration can be used. | Command option | Description | Mandatory/Optional | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| | `filePath` | The `filePath` tool option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | -| `id` | Id for the generation module | Mandatory | +| `id` | Id for the generated module. | Mandatory | | `targetModule` | The Ballerina files are generated at the given directory name in the Ballerina package. | Optional | -| `options.mode` | Mode type can be client. It generates client stubs for the given OpenAPI contract. | Optional | +| `options.mode` | The mode type can be `client`. It generates client stubs for the given OpenAPI contract. | Optional | | `options.tags` | To generate the Ballerina client stub with a subset of tags defined in the OpenAPI contract | Optional | | `options.operations` | To generate the Ballerina client stub with a subset of operations defined in the OpenAPI contract, use the `options.operations` option and specify the operations you need as specified in the OpenAPI definition. | Optional | -| `options.license` | To generate the Ballerina files with the given copyright or license header, you can use this `options.license` option with path to your copyright text. | Optional | +| `options.license` | To generate the Ballerina files with the given copyright or license header, you can use this `options.license` option with the path to your copyright text. | Optional | | `options.nullable` | If your OpenAPI specification includes JSON schema properties that are not marked as `options.nullable=true`, they may return as null in some responses. It results in a JSON schema to Ballerina record data binding error. If you suspect this can happen for any property, it is safe to generate all data types in the generated record with Ballerina nil support by turning on this flag. | Optional | | `options.clientMethods`| This option can be used in the client generation to select the client method type, which can be `resource` or `remote`. (The default option is `resource`). | Optional | | `options.statusCodeBinding`| This option can be used in the client generation to generate the client methods with status code response binding. | Optional | @@ -345,9 +345,9 @@ $ bal openapi add -i --id --module **Info:** For more command options, see [OpenAPI to Ballerina CLI options](#openapi-to-ballerina-command-options). From d060a379ddb6eb947d53ba42e14ac0339ef08695 Mon Sep 17 00:00:00 2001 From: lnash94 Date: Sat, 4 May 2024 17:12:51 +0530 Subject: [PATCH 6/6] Fix review suggestions for mode --- swan-lake/integration-tools/openapi-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index 5966d138ce5..cd4dc89c4d4 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -317,7 +317,7 @@ The below tool configuration can be used. | `filePath` | The `filePath` tool option specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | | `id` | Id for the generated module. | Mandatory | | `targetModule` | The Ballerina files are generated at the given directory name in the Ballerina package. | Optional | -| `options.mode` | The mode type can be `client`. It generates client stubs for the given OpenAPI contract. | Optional | +| `options.mode` | The supported mode type is `client`. It generates client stubs for the given OpenAPI contract. | Optional | | `options.tags` | To generate the Ballerina client stub with a subset of tags defined in the OpenAPI contract | Optional | | `options.operations` | To generate the Ballerina client stub with a subset of operations defined in the OpenAPI contract, use the `options.operations` option and specify the operations you need as specified in the OpenAPI definition. | Optional | | `options.license` | To generate the Ballerina files with the given copyright or license header, you can use this `options.license` option with the path to your copyright text. | Optional |