ballerina/openapi module

Module overview

This module provides the following code generation capabilities to Ballerina:

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html
  1. Generate the Ballerina code for a given OpenApi definition.
  2. Generate the client stub for an existing Ballerina service at build time.
  3. Export the OpenApi definition of a Ballerina service.

The openapi command in Ballerina is used for OpenApi to Ballerina and Ballerina to OpenApi code generation. Code generation from OpenApi to Ballerina can produce mock services and client stubs.

For build time client stub generation, annotation support is provided.

Mock Service from OpenApi

ballerina openapi gen-service <openapifile> [-m <module-name>|--module <module-name>] [-o <path>|--output<path>]

Generates a Ballerina service for the OpenApi file.

This generated service is a mock version of the actual service. Generated sources contain the service definition in gen/ and the resource implementation file in the module root directory with the suffix _impl. The _impl file is not overwritten by code regeneration.

Client Stub from OpenApi

ballerina openapi gen-client <openapifile> [-m <module-name>|--module <module-name>] [-o <path>|--output<path>]

Generates a Ballerina client stub for the service defined in a OpenApi file.

This client can be used in client applications to call the service defined in the OpenApi file.

Service to OpenApi Export

=======
  • Generate the Ballerina code for a given OpenAPI definition.
  • Generate the client stub for an existing Ballerina service at build time.
  • Export the OpenAPI definition of a Ballerina service.
  • The openapi command in Ballerina is used for OpenAPI to Ballerina and Ballerina to OpenAPI code generation. Code generation from OpenAPI to Ballerina can produce mock services and client stubs.

    For build time client stub generation, annotation support is provided.

    Mock Service from OpenAPI

    ballerina openapi gen-service <openapifile> [-m <module-name>|--module <module-name>] [-o <path>|--output<path>]

    Generates a Ballerina service for the OpenAPI file.

    This generated service is a mock version of the actual service. Generated sources contain the service definition in gen/ and the resource implementation file in the module root directory with the suffix _impl. The _impl file is not overwritten by code regeneration.

    Client Stub from OpenAPI

    ballerina openapi gen-client <openapifile> [-m <module-name>|--module <module-name>] [-o <path>|--output<path>]

    Generates a Ballerina client stub for the service defined in a OpenAPI file.

    This client can be used in client applications to call the service defined in the OpenAPI file.

    Service to OpenAPI Export

    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    ballerina openapi export <balfile> [-o <path>|--output<path>] [-s <servicename>|--service <servicename>]

    Export the Ballerina service to a definition of OpenApi Specification 3.0. For the export to work properly, the input Ballerina service should be defined using basic service and resource level HTTP annotations.

    Client Stub for Service

    Generates a Ballerina client stub to communicate with a Ballerina service.

    All endpoint(s) that are used for client stub generation should be marked with the @openapi:ClientEndpoint annotation. If not, there might be errors during client stub generation. Endpoints that are not marked with this annotation are not picked for client stub generation. <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html The @openapi:ClientConfig {generate: true} annotation is used to enable or disable client stub generation per service.

    Samples

    Mock Service From OpenApi

    ballerina openapi gen-service hello_service.yaml -p hello_service

    Client Stub From OpenApi

    ballerina openapi gen-client hello_service.yaml -p hello_client

    OpenApi From Service

    ballerina openapi export hello_service.bal

    Client stub From Service

    import ballerina/io;
    import ballerina/http;
    import ballerina/openapi;
    =======
    The @openapi:ClientConfig { generate: true } annotation is used to enable or disable client stub generation per service.

    Samples

    Mock Service From OpenAPI

    ballerina openapi gen-service hello_service.yaml -p hello_service

    Client Stub From OpenAPI

    ballerina openapi gen-client hello_service.yaml -p hello_client

    OpenAPI From Service

    ballerina openapi export hello_service.bal

    Client stub From Service

    import ballerina/http;
    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    import ballerina/log;
    import ballerina/openapi;
    
    // Define this endpoint as a selected endpoint for client generation.
    @openapi:ClientEndpoint
    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html
    endpoint http:Listener helloEp {
        port: 9090
    };
    =======
    listener http:Listener helloEp = new(9090);
    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    
    // Enable client code generation for this service.
    @openapi:ClientConfig {
        generate: true
    }
    @http:ServiceConfig {
        basePath: "/sample"
    }
    service Hello on helloEp {    
        @http:ResourceConfig {
            methods: ["GET"],
            path: "/hello"
        }
        resource function hello(http:Caller caller, http:Request req) {
            http:Response res = new;
            res.setPayload("Hello");
            var result = caller->respond(res);
            if (result is error) {
                log:printError("Error when responding", err = result);
            }
        }
    }
    

    Module Detail

    Records

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html
    Record Description
    ClientInformation Configuration elements for client code generation.
    ContactModel for OpenApi contact information. ======= Model for OpenAPI contact information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    DocumentationInformation Model for service documentation definition.
    EncodingModel for additional OpenApi content type definition. ======= Model for additional OpenAPI content type definition. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    ExampleModel for keeping OpenApi example information. ======= Model for keeping OpenAPI example information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    HeaderModel for keeping OpenApi header definition information. ======= Model for keeping OpenAPI header definition information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    License Model for service licence information.
    MultiResourceInformationModel for multi OpenApi operation definition for ballerina resource. ======= Model for multi openapi operation definition for ballerina resource. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    ParameterInformationModel for keeping OpenApi parameter information. ======= Model for keeping OpenAPI parameter information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    ResourceInformationModel for additional OpenApi resource definition. ======= Model for additional OpenAPI resource definition. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    ResponseModel for keeping OpenApi response information. ======= Model for keeping OpenAPI response information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    SchemaModel for keeping additional OpenApi schema information. ======= Model for keeping additional OpenAPI schema information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    SecurityRequirement Model for security requirement definition. This is most likely the OAuth scopes.
    ServiceInformationModel for additional OpenApi information of a Ballerina service. ======= Model for additional OpenAPI information of a Ballerina service. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    TagModel for OpenApi service tag definition. ======= Model for OpenAPI service tag definition. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    requestBodyModel for additional OpenApi request body details. ======= Model for additional OpenAPI request body details. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    Annotations

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html
    Name Attaches To Data Type Description
    ClientConfig service ClientInformation

    Annotation to configure client code generation.

    ClientEndpoint listener -

    Presence of this annotation will mark this endpoint to be used as a service endpoint for client generation

    MultiResourceInfo resourceMultiResourceInformation

    Annotation for multi OpenApi operation information of a Ballerina resource.

    =======
    MultiResourceInformation

    Annotation for multi OpenAPI operation information of a Ballerina resource.

    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    ResourceInfo resourceResourceInformation

    Annotation for additional OpenApi information of a Ballerina resource.

    =======
    ResourceInformation

    Annotation for additional OpenAPI information of a Ballerina resource.

    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    ServiceInfo serviceServiceInformation

    Annotation for additional OpenApi information of a Ballerina service.

    =======
    ServiceInformation

    Annotation for additional OpenAPI information of a Ballerina service.

    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    public type ClientInformation

    Configuration elements for client code generation.

    Field Name Data Type Default Value Description
    generate boolean true

    generates client code if set to true

    public type Contact

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for OpenApi contact information. ======= Model for OpenAPI contact information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    Field Name Data Type Default Value Description
    name string

    Contact name

    email string

    Contact email

    url string

    Contact web address/page

    public type DocumentationInformation

    Model for service documentation definition.

    Field Name Data Type Default Value Description
    description string

    Documentation description

    url string

    External documentation url

    public type Encoding

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for additional OpenApi content type definition. ======= Model for additional OpenAPI content type definition. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    Field Name Data Type Default Value Description
    headersopenapi:ParameterInformation[]openapi:ParameterInformation[][]

    Additional information to be provided as headers

    contentType string

    The Content-Type for encoding a specific property

    style string

    Describes how a specific property value will be serialized depending on its type

    explode boolean false

    Should property values of array or object generate separate parameters for each value of the array

    allowReserved boolean false

    Determines whether the parameter value SHOULD allow reserved characters

    public type Example

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for keeping OpenApi example information. ======= Model for keeping OpenAPI example information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    Field Name Data Type Default Value Description
    summary string

    Short description for the example

    description string

    Long description for the example

    value any

    Any example value

    externalValue string

    A URL that points to the literal example

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for keeping OpenApi header definition information. ======= Model for keeping OpenAPI header definition information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    Field Name Data Type Default Value Description
    required boolean false

    Is this a required header

    discontinued boolean false

    Is this header deprecated

    description string

    Header description

    public type License

    Model for service licence information.

    Field Name Data Type Default Value Description
    name string

    License name

    url string

    License url

    public type MultiResourceInformation

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for multi OpenApi operation definition for ballerina resource. ======= Model for multi openapi operation definition for ballerina resource. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    Field Name Data Type Default Value Description
    resourceInformation map<openapi:ResourceInformation>

    list of resource information

    public type ParameterInformation

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for keeping OpenApi parameter information. ======= Model for keeping OpenAPI parameter information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    Field Name Data Type Default Value Description
    inInfo string

    Where the parameter is located. Ex: query

    name string

    Parameter name

    paramType string

    Parameter type

    description string

    Description of the parameter

    required boolean false

    Is this parameter MUST be present in the request

    discontinued boolean false

    Is this parameter deprecated

    allowEmptyValue string

    Is an empty value allowed for this parameter. Valid only for query parameters

    schemaopenapi:Schemaopenapi:Schema {}

    Parameter data type

    public type ResourceInformation

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for additional OpenApi resource definition. ======= Model for additional OpenAPI resource definition. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    Field Name Data Type Default Value Description
    tags string[] []

    Tags attched to this resource

    summary string

    A short summary of what the operation does

    description string

    A verbose explanation of the operation behavior

    externalDocsopenapi:DocumentationInformationopenapi:DocumentationInformation {}

    Additional documentation for this operation

    parametersopenapi:ParameterInformation[]openapi:ParameterInformation[][]

    A list of parameters that are applicable for this operation

    public type Response

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for keeping OpenApi response information. ======= Model for keeping OpenAPI response information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    Field Name Data Type Default Value Description
    code string

    Reponse code

    description string

    Response description

    response string

    Response content

    headersopenapi:Header[]openapi:Header[][]

    Response headers

    examplesopenapi:Example[]openapi:Example[][]

    Examples for this response

    public type Schema

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for keeping additional OpenApi schema information. ======= Model for keeping additional OpenAPI schema information. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html
    Field Name Data Type Default Value Description
    format string

    Data format as specified by OpenApi data type

    =======

    Data format as specified by OpenAPI data type

    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    isArray boolean false

    Is this an array type schema

    ref string

    Schema reference if this schema definition is a reference type definition

    public type SecurityRequirement

    Model for security requirement definition. This is most likely the OAuth scopes.

    Field Name Data Type Default Value Description
    name string

    Security scheme name

    requirements string[] []

    Array of security requirements

    public type ServiceInformation

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for additional OpenApi information of a Ballerina service. ======= Model for additional OpenAPI information of a Ballerina service. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    Field Name Data Type Default Value Description
    title string

    Title of the OpenApi definition

    =======

    Title of the OpenAPI definition

    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    serviceVersion string

    Version of the OpenApi API

    =======

    Version of the OpenAPI

    >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    description string

    Description of the service

    termsOfService string

    Service usage terms and conditions

    contactopenapi:Contactopenapi:Contact {}

    Contact information for the exposed API

    licenseopenapi:Licenseopenapi:License {}

    License information for the exposed API

    externalDocsopenapi:DocumentationInformationopenapi:DocumentationInformation {}

    Additional external documentation

    tagsopenapi:Tag[]openapi:Tag[][]

    A list of tags used by the specification with additional metadata

    securityopenapi:SecurityRequirement[]openapi:SecurityRequirement[][]

    Security requirements for this service

    public type Tag

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for OpenApi service tag definition. ======= Model for OpenAPI service tag definition. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    Field Name Data Type Default Value Description
    name string

    Tag name

    description string

    Tag decription

    externalDocsopenapi:DocumentationInformationopenapi:DocumentationInformation {}

    Optional documentation on the tag

    public type requestBody

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html Model for additional OpenApi request body details. ======= Model for additional OpenAPI request body details. >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html

    <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html <<<<<<< HEAD:api-docs/docs/ballerina/swagger.html ======= >>>>>>> 94bf3648b61bbaf57173908d38b90ff3f3a32e94:api-docs/docs/ballerina/openapi.html
    Field Name Data Type Default Value Description
    description string

    Brief description of the request body

    required boolean false

    Determines if the request body is required in the request

    example string

    Example of the request body media type

    examplesopenapi:Example[]openapi:Example[][]

    Examples of the media type

    schemaopenapi:Schemaopenapi:Schema {}

    The schema defining the type used for the request body

    encodingopenapi:Encoding[]openapi:Encoding[][]

    Encoding and content type details