OpenAPI

The sections below include information about the usages of the Ballerina OpenAPI tool.

OpenAPI to Ballerina

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

bal openapi [-i | --input] <openapi-contract-file-path> 
            [-o | --output] <output-location>
            [--mode] <mode-type>
            [--tags] <tag-names> 
            [--operations] <operation-names> 
            [-n | --nullable]
            [--license] <license-file-path> 
            [--with-tests]

The command line arguments below can be used with the command for each particular purpose as described below.

Argument Description
-i \| --input The openapi-contract-path parameter specifies the path of the OpenAPI contract file (e.g., my-api.yaml or my-api.json) and is mandatory.
-o \| --output The Ballerina files will be generated at the same location from which the OpenAPI command is executed. Optionally, you can point to another directory location by using the optional flag (-o\|--output).
--mode Mode type is optional and can be either a service or client. The Ballerina service and client will be generated according to the mode. Without the --mode, it will generate both service and client stubs for the given OpenAPI contract.
--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 <openapi-contract> [--tags < "tag1","tag2">]
--operations To generate the Ballerina client or service stub with a subset of operations defined in the OpenAPI contract, use the --operations option and specify the operations you need as specified in the OpenAPI definition.

E.g., bal openapi -i <openapi-contract> [--operations <"op1", "op2">]
--license To generate the Ballerina files with the given copyright or license header, you can use this --license flag with your copyright text.

E.g., bal openapi -i <openapi-contract> [--license <license-file-path>]
-n \|--nullable This is an optional flag in the OpenAPI to Ballerina command. If your OpenAPI specification includes JSON schema properties that are not marked as nullable:true, they may return as null in some responses. It will result 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 <openapi-contract> [-n \|--nullable]
--with-tests This is optional. It works with the client generation command and generates a boiler-plate test for all the remote functions of the generated client.

Ballerina to OpenAPI

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

bal openapi [-i | --input] <ballerina-service-file-path> [--json]
            [-s | --service] <current-service-name>
            [-o | --output] <output-location>

The command line arguments below can be used with the command for each particular purpose as described below.

Argument Description
-i \|--input The ballerina-service-file-path parameter specifies the path of the Ballerina service file (e.g., my-service.bal) and is mandatory.
--json Generate the Ballerina service to OpenAPI output as JSON. The default is YAML.
-s \| --service This service name is used to identify the service that needs to be documented as an OpenAPI specification.
-o\|--output Location of the generated OpenAPI specification. If this path is not specified, the output will be written to the same directory from which the command is run.