diff --git a/swan-lake/integration-tools/openapi-tool.md b/swan-lake/integration-tools/openapi-tool.md index c0e8ce158bf..c832562a1d9 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 contract usage + +The Sanitize OpenAPI command supports several options 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 contract usage + +The Flatten OpenAPI command supports several options 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 contract + +The following command-line options are available. + +| 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 contract + +The following command-line options are available. + +| 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. @@ -942,3 +994,207 @@ 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-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. + +``` +bal openapi sanitize [-i | --input] + [-o | --output] + [-n | --name] + [-f | --format] [json|yaml] + [-t | --tags] + [--operations] +``` + +The command-line options are as follows. + +| 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 | + +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 objects + +The `flatten` 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 options are as follows. + +| 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 | + +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 +```