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.

ArgumentDescription
-i | --inputThe 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 | --outputThe Ballerina files are 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).
--modeMode type is optional and 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.
--tagsTo 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">]
--operationsTo 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">]
--licenseTo 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 |--nullableThis 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 results 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-testsThis 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.

ArgumentDescription
-i |--inputThe ballerina-service-file-path parameter specifies the path of the Ballerina service file (e.g., my-service.bal) and is mandatory.
--jsonGenerate the Ballerina service to OpenAPI output as JSON. The default is YAML.
-s | --serviceThis service name is used to identify the service that needs to be documented as an OpenAPI specification.
-o|--outputLocation of the generated OpenAPI specification. If this path is not specified, the output is written to the same directory from which the command is run.