Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update OpenAPI learn page #9626

Closed
wants to merge 6 commits into from
Closed

Update OpenAPI learn page #9626

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
18231f0
Update OpenAPI learn page
lnash94 Nov 29, 2024
091d861
Fix review suggestion
lnash94 Dec 13, 2024
abed047
Apply suggestions from code review
TharmiganK Dec 18, 2024
0ffae86
Address review suggestions
TharmiganK Dec 20, 2024
34fd1d5
Apply changes from the code review
SachinAkash01 Jan 3, 2025
3cebb3a
Merge pull request #5 from SachinAkash01/u11-openapi-learn-page
lnash94 Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 58 additions & 6 deletions swan-lake/integration-tools/openapi-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,17 +46,43 @@ $ bal openapi [-i | --input] <ballerina-service-file-path> [--json]
[-o | --output] <output-location>
```

### Sanitize OpenAPI
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sanitize OpenAPI what? Can we be more specific?

Copy link
Member Author

@lnash94 lnash94 Jan 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about changing this title to the "OpenAPI sanitize command usage" or "OpenAPI sanitize CLI usage"
WDYT @TharmiganK , @SachinAkash01

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or maybe we can use Sanitize OpenAPI contract usage since it gives more context on what we are doing? @lnash94 @TharmiganK

Copy link
Member Author

@lnash94 lnash94 Jan 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In addition to that, considering the various CLI commands available in OpenAPI tool, prefer to use command options instead of usage for the title. The term usage typically implies a broader scenario in which this functionality might be employed.

For example, in a Ballerina-to-OpenAPI context, 'usage' could include references to CLI commands, compiler plugins, or built-in plugins.

However, in this specific section, we are focusing on CLI options. we need to address this change in other CLI title as well.


The Ballerina to OpenAPI command supports several usages in the Ballerina OpenAPI tool as follows.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence seems to be generic. Can we relate it to the title please?

lnash94 marked this conversation as resolved.
Show resolved Hide resolved

```
bal openapi sanitize [-i | --input] <openapi-contract-file-path>
[-o | --output] <output-file-path>
[-n | --name] <generated-file-name>
[-f | --format] [json|yaml]
[-t | --tags] <tag-names>
[--operations] <operation-names>
```

### Flatten OpenAPI

The Ballerina to OpenAPI command supports several usages in the Ballerina OpenAPI tool as follows.

```
bal openapi flatten [-i | --input] <openapi-contract-file-path>
[-o | --output] <output-file-path>
[-n | --name] <generated-file-name>
[-f | --format] [json|yaml]
[-t | --tags] <tag-names>
[--operations] <operation-names>
```

## 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.<br><br>**E.g.,** `bal openapi -i <openapi-contract> [--tags < "tag1","tag2">]` | Optional |
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still don't think is necessary. Can just say something along the lines of the following 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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrasing is not uniform with the rest. Starts with "This ...", unlike others.

| `-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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would describe the option first and then say if not specified, ...

| `-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.
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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 |
Expand Down