From 18231f0e79115f888314cc305c9274a789a7f677 Mon Sep 17 00:00:00 2001 From: lnash94 Date: Fri, 29 Nov 2024 15:38:07 +0530 Subject: [PATCH 1/5] Update OpenAPI learn page --- swan-lake/integration-tools/openapi-tool.md | 198 ++++++++++++++++++++ 1 file changed, 198 insertions(+) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index c0e8ce158bf..6a7b470126e 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -942,3 +942,201 @@ The attributes of the annotation are optional and can be used for each particula | `licenseName: string` | You can use this to add the name of the license under which the API is provided. | Optional | | `licenseURL: string` | You can use this to add the URL details regarding the full text of the license. | Optional | | `embed: string` | Turns on generating OpenAPI documentation for the service for [introspection endpoint](https://ballerina.io/spec/http/#236-openapi-specification-resources) support when used with `true` in the annotation. | Optional | + +## OpenAPI Contract Modifier + +### Modify the OpenAPI Contract Using Ballerina-Friendly Naming Conventions + +The `sanitize` subcommand sanitizes the OpenAPI contract file according to the best practices of Ballerina. The Ballerina-specific name extension x-ballerina-name is added to the schemas, including query names and object property names, which cannot be modified directly. + +``` +bal openapi sanitize [-i | --input] + [-o | --output] + [-n | --name] + [-f | --format] [json|yaml] + [-t | --tags] + [--operations] +``` +The command-line arguments below can be used with the command for each particular purpose as described below. + +| 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 | +| `-o \| --output` | The modified openapi file is generated at the same location from which the `bal openapi sanitize` command is executed. You can point to another directory location by using the `(-o\|--output).` flag. | Optional | +| `-n \| --name` | The given name will be used to save the sanitized OpenAPI contract. The default name is `sanitized_openapi`. | Optional | +| `-f \| --format` | The sanitized OpenAPI contract will be saved in the given format. The format can be either JSON or YAML.The default format is same as the input file format. | Optional | +| `-t \| --tags` | The sanitized OpenAPI contract will only have the operations with the given tags. | Optional | +| `--operations` | The sanitized OpenAPI contract will only have the given operations. | Optional | + +For example, + +**Input OpenAPI contract file:** +```yaml +paths: + /albums: + get: + tags: + - albums + operationId: getAlbums + parameters: + - name: _artists_ + in: query + schema: + type: array + items: + type: string + responses: + "200": + description: Ok + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/album" +components: + schemas: + album: + required: + - _id + - artist + - title + type: object + properties: + _id: + type: string + title: + type: string + artist: + type: string + additionalProperties: false +``` +**Output OpenAPI contract file:** +```yaml +paths: + /albums: + get: + tags: + - albums + operationId: getAlbums + parameters: + - name: _artists_ + in: query + schema: + type: array + items: + type: string + x-ballerina-name: artists -->//Ballerina name extension + responses: + "200": + description: Ok + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Album" +components: + schemas: + Album: + required: + - _id\- + - artist + - title + type: object + properties: + _id\-: + type: string + x-ballerina-name: id + artist: + type: string + title: + type: string + additionalProperties: false +``` + +### Modify the OpenAPI Contract by defining named objects for inline object + +The `fallten` subcommand makes the OpenAPI contract more readable by relocating all inline embedded schemas to the components section. + +``` +bal openapi flatten [-i | --input] + [-o | --output] + [-n | --name] + [-f | --format] [json|yaml] + [-t | --tags] + [--operations] +``` +The command-line arguments below can be used with the command for each particular purpose as described below. + +| 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 | +| `-o \| --output` | The modified openapi file is generated at the same location from which the `bal openapi flatten` command is executed. You can point to another directory location by using the `(-o\|--output).` flag. | Optional | +| `-n \| --name` | The given name will be used to save the flattened OpenAPI contract. The default name is `flattened_openapi`. | Optional | +| `-f \| --format` | The flattened OpenAPI contract will be saved in the given format. The format can be either JSON or YAML.The default format is same as the input file format. | Optional | +| `-t \| --tags` | The falttened OpenAPI contract will only have the operations with the given tags. | Optional | +| `--operations` | The falltened OpenAPI contract will only have the given operations. | Optional | + +For example, + +**Input OpenAPI contract file:** +```yaml +... +paths: + /pets: + get: + summary: List all pets + operationId: listPets + tags: + - pets + responses: + '200': + description: An paged array of pets + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + tag: + type: string +``` +**Output OpenAPI contract file:** +```yaml +... +paths: + /pets: + get: + tags: + - pets + summary: List all pets + operationId: listPets + responses: + "200": + description: An paged array of pets + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/InlineResponse200" +components: + schemas: + InlineResponse200: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + tag: + type: string +``` From 091d861afb5e6a7564cdcb5108e1a26a6b3adc5c Mon Sep 17 00:00:00 2001 From: lnash94 Date: Fri, 13 Dec 2024 22:10:50 +0530 Subject: [PATCH 2/5] Fix review suggestion --- swan-lake/integration-tools/openapi-tool.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index 6a7b470126e..f0a842f8866 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -947,7 +947,7 @@ The attributes of the annotation are optional and can be used for each particula ### Modify the OpenAPI Contract Using Ballerina-Friendly Naming Conventions -The `sanitize` subcommand sanitizes the OpenAPI contract file according to the best practices of Ballerina. The Ballerina-specific name extension x-ballerina-name is added to the schemas, including query names and object property names, which cannot be modified directly. +The `sanitize` subcommand sanitizes the OpenAPI contract file according to the naming conventions of Ballerina. The Ballerina-specific name extension `x-ballerina-name` is added to the schemas, including query names and object property names, which cannot be modified directly. ``` bal openapi sanitize [-i | --input] @@ -1040,12 +1040,12 @@ components: schemas: Album: required: - - _id\- + - _id - artist - title type: object properties: - _id\-: + _id: type: string x-ballerina-name: id artist: From abed0472033ac721a4369b8498601c9d9e0630ed Mon Sep 17 00:00:00 2001 From: Krishnananthalingam Tharmigan <63336800+TharmiganK@users.noreply.github.com> Date: Wed, 18 Dec 2024 10:24:29 +0530 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Maryam Ziyad --- swan-lake/integration-tools/openapi-tool.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index f0a842f8866..978623d0925 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -957,20 +957,22 @@ bal openapi sanitize [-i | --input] [-t | --tags] [--operations] ``` -The command-line arguments below can be used with the command for each particular purpose as described below. + +The command-line options are as follows. | 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 | -| `-o \| --output` | The modified openapi file is generated at the same location from which the `bal openapi sanitize` command is executed. You can point to another directory location by using the `(-o\|--output).` flag. | Optional | +| `-o \| --output` | The modified OpenAPI file is generated at the same location from which the `bal openapi sanitize` command is executed. You can point to another directory using the `(-o\|--output)` option. | Optional | | `-n \| --name` | The given name will be used to save the sanitized OpenAPI contract. The default name is `sanitized_openapi`. | Optional | -| `-f \| --format` | The sanitized OpenAPI contract will be saved in the given format. The format can be either JSON or YAML.The default format is same as the input file format. | Optional | +| `-f \| --format` | The sanitized OpenAPI contract will be saved in the given format. The format can be either JSON or YAML. The default format is same as the input file format. | Optional | | `-t \| --tags` | The sanitized OpenAPI contract will only have the operations with the given tags. | Optional | | `--operations` | The sanitized OpenAPI contract will only have the given operations. | Optional | For example, **Input OpenAPI contract file:** + ```yaml paths: /albums: @@ -1011,7 +1013,9 @@ components: type: string additionalProperties: false ``` + **Output OpenAPI contract file:** + ```yaml paths: /albums: @@ -1055,9 +1059,9 @@ components: additionalProperties: false ``` -### Modify the OpenAPI Contract by defining named objects for inline object +### Modify the OpenAPI Contract by defining named objects for inline objects -The `fallten` subcommand makes the OpenAPI contract more readable by relocating all inline embedded schemas to the components section. +The `flatten` subcommand makes the OpenAPI contract more readable by relocating all inline embedded schemas to the components section. ``` bal openapi flatten [-i | --input] @@ -1067,7 +1071,8 @@ bal openapi flatten [-i | --input] [-t | --tags] [--operations] ``` -The command-line arguments below can be used with the command for each particular purpose as described below. + +The command-line options are as follows. | Command option | Description | Mandatory/Optional | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| @@ -1081,6 +1086,7 @@ The command-line arguments below can be used with the command for each particula For example, **Input OpenAPI contract file:** + ```yaml ... paths: From 0ffae869cfe37038505105475a276d0c539f066c Mon Sep 17 00:00:00 2001 From: Krishnananthalingam Tharmigan <63336800+TharmiganK@users.noreply.github.com> Date: Fri, 20 Dec 2024 14:44:26 +0530 Subject: [PATCH 4/5] Address review suggestions --- swan-lake/integration-tools/openapi-tool.md | 64 +++++++++++++++++++-- 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index 978623d0925..f3e3d884d5d 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -46,17 +46,43 @@ $ bal openapi [-i | --input] [--json] [-o | --output] ``` +### Sanitize OpenAPI + +The Ballerina to OpenAPI command supports several usages in the Ballerina OpenAPI tool as follows. + +``` +bal openapi sanitize [-i | --input] + [-o | --output] + [-n | --name] + [-f | --format] [json|yaml] + [-t | --tags] + [--operations] +``` + +### Flatten OpenAPI + +The Ballerina to OpenAPI command supports several usages in the Ballerina OpenAPI tool as follows. + +``` +bal openapi flatten [-i | --input] + [-o | --output] + [-n | --name] + [-f | --format] [json|yaml] + [-t | --tags] + [--operations] +``` + ## Command options The below command-line arguments can be used with the command. -### OpenAPI to Ballerina command options +### OpenAPI to Ballerina The command-line arguments below can be used with the command for each particular purpose as described below. | 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` | This specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | | `-o \| --output` | The Ballerina files are generated at the same location from which the `bal openapi` command is executed. You can point to another directory location by using the `(-o\|--output).` flag. | Optional | | `--mode` | Mode type can be either a service or client. The Ballerina service and client are generated according to the mode. Without the `--mode`, it generates both service and client stubs for the given OpenAPI contract. | Optional | | `--tags` | To generate the Ballerina client or service stub with a subset of tags defined in the OpenAPI contract, use the `--tags` option and specify the tags you need as specified in the OpenAPI definition.

**E.g.,** `bal openapi -i [--tags < "tag1","tag2">]` | Optional | @@ -71,17 +97,43 @@ The command-line arguments below can be used with the command for each particula | `--single-file` | This option can be used to generate the Ballerina service or client with related types and utility functions in a single file. | Optional | | `--use-sanitized-oas` | This is an experimental feature. This option enables service/client code generation by modifying the given OAS to follow Ballerina language best practices. | Optional | -### Ballerina to OpenAPI command options +### Ballerina to OpenAPI The command-line arguments below can be used with the command for each particular purpose as described below. | Command option | Description | Mandatory/Optional | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| -| `-i \|--input` | The `ballerina-service-file-path` command option specifies the path of the Ballerina service file (e.g., `my-service.bal`). | Mandatory | +| `-i \|--input` | This specifies the path of the Ballerina service file (e.g., `my-service.bal`). | Mandatory | | `--json` | Generate the Ballerina service to OpenAPI output as JSON. The default is YAML. | Optional | | `-s \| --service` | This service name is used to identify the service that needs to be documented as an OpenAPI contract. | Optional | | `-o\|--output` | Location of the generated OpenAPI contract. If this path is not specified, the output is written to the same directory from which the command is run. | Optional | +### Sanitize OpenAPI + +The command-line arguments below can be used with the command for each particular purpose as described below. + +| Command option | Description | Mandatory/Optional | +|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| +| `-i \| --input` | This specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | +| `-o \| --output` | The modified OpenAPI file is generated at the same location from which the `bal openapi sanitize` command is executed. You can point to another directory using the `(-o\|--output)` option. | Optional | +| `-n \| --name` | The given name will be used to save the sanitized OpenAPI contract. The default name is `sanitized_openapi`. | Optional | +| `-f \| --format` | The sanitized OpenAPI contract will be saved in the given format. The format can be either JSON or YAML. The default format is same as the input file format. | Optional | +| `-t \| --tags` | The sanitized OpenAPI contract will only have the operations with the given tags. | Optional | +| `--operations` | The sanitized OpenAPI contract will only have the given operations. | Optional | + +### Flatten OpenAPI + +The command-line arguments below can be used with the command for each particular purpose as described below. + +| Command option | Description | Mandatory/Optional | +|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| +| `-i \| --input` | This specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | +| `-o \| --output` | The modified openapi file is generated at the same location from which the `bal openapi flatten` command is executed. You can point to another directory location by using the `(-o\|--output).` flag. | Optional | +| `-n \| --name` | The given name will be used to save the flattened OpenAPI contract. The default name is `flattened_openapi`. | Optional | +| `-f \| --format` | The flattened OpenAPI contract will be saved in the given format. The format can be either JSON or YAML.The default format is same as the input file format. | Optional | +| `-t \| --tags` | The falttened OpenAPI contract will only have the operations with the given tags. | Optional | +| `--operations` | The falltened OpenAPI contract will only have the given operations. | Optional | + ## Generate Ballerina services from OpenAPI Contracts If you are an API developer who prefers the **design-first approach**, you can use an existing or your OpenAPI definition to generate Ballerina services using the `bal openapi` CLI command as follows. @@ -962,7 +1014,7 @@ The command-line options are as follows. | 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` | This specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | | `-o \| --output` | The modified OpenAPI file is generated at the same location from which the `bal openapi sanitize` command is executed. You can point to another directory using the `(-o\|--output)` option. | Optional | | `-n \| --name` | The given name will be used to save the sanitized OpenAPI contract. The default name is `sanitized_openapi`. | Optional | | `-f \| --format` | The sanitized OpenAPI contract will be saved in the given format. The format can be either JSON or YAML. The default format is same as the input file format. | Optional | @@ -1076,7 +1128,7 @@ The command-line options are as follows. | 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` | This specifies the path of the OpenAPI contract file (e.g., `my-api.yaml` or `my-api.json`). | Mandatory | | `-o \| --output` | The modified openapi file is generated at the same location from which the `bal openapi flatten` command is executed. You can point to another directory location by using the `(-o\|--output).` flag. | Optional | | `-n \| --name` | The given name will be used to save the flattened OpenAPI contract. The default name is `flattened_openapi`. | Optional | | `-f \| --format` | The flattened OpenAPI contract will be saved in the given format. The format can be either JSON or YAML.The default format is same as the input file format. | Optional | From 34fd1d5aea42c850f3549cd1208c1419e4aef95b Mon Sep 17 00:00:00 2001 From: SachinAkash01 Date: Fri, 3 Jan 2025 13:57:12 +0530 Subject: [PATCH 5/5] Apply changes from the code review --- swan-lake/integration-tools/openapi-tool.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index f3e3d884d5d..c832562a1d9 100644 --- a/swan-lake/integration-tools/openapi-tool.md +++ b/swan-lake/integration-tools/openapi-tool.md @@ -46,9 +46,9 @@ $ bal openapi [-i | --input] [--json] [-o | --output] ``` -### Sanitize OpenAPI +### Sanitize OpenAPI contract usage -The Ballerina to OpenAPI command supports several usages in the Ballerina OpenAPI tool as follows. +The Sanitize OpenAPI command supports several options in the Ballerina OpenAPI tool as follows. ``` bal openapi sanitize [-i | --input] @@ -59,9 +59,9 @@ bal openapi sanitize [-i | --input] [--operations] ``` -### Flatten OpenAPI +### Flatten OpenAPI contract usage -The Ballerina to OpenAPI command supports several usages in the Ballerina OpenAPI tool as follows. +The Flatten OpenAPI command supports several options in the Ballerina OpenAPI tool as follows. ``` bal openapi flatten [-i | --input] @@ -108,9 +108,9 @@ The command-line arguments below can be used with the command for each particula | `-s \| --service` | This service name is used to identify the service that needs to be documented as an OpenAPI contract. | Optional | | `-o\|--output` | Location of the generated OpenAPI contract. If this path is not specified, the output is written to the same directory from which the command is run. | Optional | -### Sanitize OpenAPI +### Sanitize OpenAPI contract -The command-line arguments below can be used with the command for each particular purpose as described below. +The following command-line options are available. | Command option | Description | Mandatory/Optional | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| @@ -121,9 +121,9 @@ The command-line arguments below can be used with the command for each particula | `-t \| --tags` | The sanitized OpenAPI contract will only have the operations with the given tags. | Optional | | `--operations` | The sanitized OpenAPI contract will only have the given operations. | Optional | -### Flatten OpenAPI +### Flatten OpenAPI contract -The command-line arguments below can be used with the command for each particular purpose as described below. +The following command-line options are available. | Command option | Description | Mandatory/Optional | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| @@ -997,7 +997,7 @@ The attributes of the annotation are optional and can be used for each particula ## OpenAPI Contract Modifier -### Modify the OpenAPI Contract Using Ballerina-Friendly Naming Conventions +### Modify the OpenAPI contract using Ballerina-Preferred naming conventions The `sanitize` subcommand sanitizes the OpenAPI contract file according to the naming conventions of Ballerina. The Ballerina-specific name extension `x-ballerina-name` is added to the schemas, including query names and object property names, which cannot be modified directly.