ballerina/openapi module

Module overview

This module provides the following code generation capabilities to Ballerina:

  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

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. 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;
import ballerina/log;
import ballerina/openapi;

// Define this endpoint as a selected endpoint for client generation.
@openapi:ClientEndpoint
listener http:Listener helloEp = new(9090);

// 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);
        }
    }
}

Annotations

Name Attachement Points 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 resource MultiResourceInformation

Annotation for multi OpenAPI operation information of a Ballerina resource.

ResourceInfo resource ResourceInformation

Annotation for additional OpenAPI information of a Ballerina resource.

ServiceInfo service ServiceInformation

Annotation for additional OpenAPI information of a Ballerina service.

Records Summary

Record Description
ClientInformation Configuration elements for client code generation.
Contact Model for OpenAPI contact information.
DocumentationInformation Model for service documentation definition.
Encoding Model for additional OpenAPI content type definition.
Example Model for keeping OpenAPI example information.
Header Model for keeping OpenAPI header definition information.
License Model for service licence information.
MultiResourceInformation Model for multi openapi operation definition for ballerina resource.
ParameterInformation Model for keeping OpenAPI parameter information.
ResourceInformation Model for additional OpenAPI resource definition.
Response Model for keeping OpenAPI response information.
Schema Model for keeping additional OpenAPI schema information.
SecurityRequirement Model for security requirement definition. This is most likely the OAuth scopes.
ServiceInformation Model for additional OpenAPI information of a Ballerina service.
Tag Model for OpenAPI service tag definition.
requestBody Model for additional OpenAPI request body details.

public type ClientInformation record

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 record

Model for OpenAPI contact information.

Field Name Data Type Default Value Description
name string

Contact name

email string

Contact email

url string

Contact web address/page

public type DocumentationInformation record

Model for service documentation definition.

Field Name Data Type Default Value Description
description string

Documentation description

url string

External documentation url

public type Encoding record

Model for additional OpenAPI content type definition.

Field Name Data Type Default Value Description
headers 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 record

Model for keeping OpenAPI example information.

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

Model for keeping OpenAPI header definition information.

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 record

Model for service licence information.

Field Name Data Type Default Value Description
name string

License name

url string

License url

public type MultiResourceInformation record

Model for multi openapi operation definition for ballerina resource.

Field Name Data Type Default Value Description
resourceInformation map

list of resource information

public type ParameterInformation record

Model for keeping OpenAPI parameter information.

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

schema openapi:Schema {}

Parameter data type

public type ResourceInformation record

Model for additional OpenAPI resource definition.

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

externalDocs openapi:DocumentationInformation {}

Additional documentation for this operation

parameters openapi:ParameterInformation[] []

A list of parameters that are applicable for this operation

public type Response record

Model for keeping OpenAPI response information.

Field Name Data Type Default Value Description
code string

Reponse code

description string

Response description

response string

Response content

headers openapi:Header[] []

Response headers

examples openapi:Example[] []

Examples for this response

public type Schema record

Model for keeping additional OpenAPI schema information.

Field Name Data Type Default Value Description
format string

Data format as specified by OpenAPI data type

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 record

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 record

Model for additional OpenAPI information of a Ballerina service.

Field Name Data Type Default Value Description
title string

Title of the OpenAPI definition

serviceVersion string

Version of the OpenAPI

description string

Description of the service

termsOfService string

Service usage terms and conditions

contact openapi:Contact {}

Contact information for the exposed API

license openapi:License {}

License information for the exposed API

externalDocs openapi:DocumentationInformation {}

Additional external documentation

tags openapi:Tag[] []

A list of tags used by the specification with additional metadata

security openapi:SecurityRequirement[] []

Security requirements for this service

public type Tag record

Model for OpenAPI service tag definition.

Field Name Data Type Default Value Description
name string

Tag name

description string

Tag decription

externalDocs openapi:DocumentationInformation {}

Optional documentation on the tag

public type requestBody record

Model for additional OpenAPI request body details.

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

examples openapi:Example[] []

Examples of the media type

schema openapi:Schema {}

The schema defining the type used for the request body

encoding openapi:Encoding[] []

Encoding and content type details