Update OpenAPI learn page #9626
Conversation
lnash94
force-pushed
the
u11-openapi-learn-page
branch
from
659cfbc to
69f0bb0
Compare
lnash94
force-pushed
the
u11-openapi-learn-page
branch
3 times, most recently
from
df0feb7 to
982df9e
Compare
lnash94
force-pushed
the
u11-openapi-learn-page
branch
from
982df9e to
18231f0
Compare
Co-authored-by: Maryam Ziyad <[email protected]>
| @@ -46,17 +46,43 @@ $ bal openapi [-i | --input] <ballerina-service-file-path> [--json] | |||
| [-o | --output] <output-location> | |||
| ``` | |||
|
|
|||
| ### Sanitize OpenAPI | |||
|
|
|||
| The Ballerina to OpenAPI command supports several usages in the Ballerina OpenAPI tool as follows. | |||
There was a problem hiding this comment.
This sentence seems to be generic. Can we relate it to the title please?
| @@ -46,17 +46,43 @@ $ bal openapi [-i | --input] <ballerina-service-file-path> [--json] | |||
| [-o | --output] <output-location> | |||
| ``` | |||
|
|
|||
| ### Sanitize OpenAPI | |||
There was a problem hiding this comment.
Sanitize OpenAPI what? Can we be more specific?
There was a problem hiding this comment.
How about changing this title to the "OpenAPI sanitize command usage" or "OpenAPI sanitize CLI usage"
WDYT @TharmiganK , @SachinAkash01
There was a problem hiding this comment.
Or maybe we can use Sanitize OpenAPI contract usage since it gives more context on what we are doing? @lnash94 @TharmiganK
There was a problem hiding this comment.
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.
| | `--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. |
There was a problem hiding this comment.
Still don't think is necessary. Can just say something along the lines of the following options are available.
Apply changes from the code review
| @@ -46,17 +46,43 @@ $ bal openapi [-i | --input] <ballerina-service-file-path> [--json] | |||
| [-o | --output] <output-location> | |||
| ``` | |||
|
|
|||
| ### Sanitize OpenAPI contract usage | |||
|
|
|||
| The Sanitize OpenAPI command supports several options in the Ballerina OpenAPI tool as follows. | |||
There was a problem hiding this comment.
| The Sanitize OpenAPI command supports several options in the Ballerina OpenAPI tool as follows. | |
| The `sanitize` subcommand of the Ballerina OpenAPI tool supports the following options. |
| | `--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 |
There was a problem hiding this comment.
Wouldn't it be clearer to have the option descriptions where they are mentioned above?
| | 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 | |
There was a problem hiding this comment.
I would describe the option first and then say if not specified, ...
|
|
||
| | 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 | |
There was a problem hiding this comment.
The phrasing is not uniform with the rest. Starts with "This ...", unlike others.
|
Closing this PR since the changes will be included in #9663 |
Purpose
Checklist
Page addition
permalinkto pages.Page removal
redirect_fromon the alternative page.redirections.jsfile.Page rename
redirect_from.redirect_to:(if applicable).Page restrcuture
permalinkto pages.redirect_from.redirect_to:(if applicable).