ballerina/swagger package

Package overview

This package provides the following code generation capabilities to Ballerina:

  1. Generate the Ballerina code for a given Swagger definition.
  2. Generate the client stub for an existing Ballerina service at build time.
  3. Export the Swagger definition of a Ballerina service.

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

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

Mock Service from Swagger

ballerina swagger mock <swaggerfile> [-p packagename>|--package <packagename>] [-o <path>|--output<path>]

Generates a Ballerina service for the Swagger 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 package root directory with the suffix _impl. The _impl file is not overwritten by code regeneration.

Client Stub from Swagger

ballerina swagger client <swaggerfile> [-p packagename>|--package <packagename>] [-o <path>|--output<path>]

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

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

Service to Swagger Export

ballerina swagger 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 @swagger: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 @swagger:ClientConfig {generate: true} annotation is used to enable or disable client stub generation per service.

Samples

Mock Service From Swagger

ballerina swagger mock hello_service.yaml -p hello_service

Client Stub From Swagger

ballerina swagger client hello_service.yaml -p hello_client

Swagger From Service

ballerina swagger export hello_service.bal

Client stub From Service

import ballerina/io;
import ballerina/http;
import ballerina/swagger;
import ballerina/log;

// Define this endpoint as a selected endpoint for client generation.
@swagger:ClientEndpoint
endpoint http:Listener helloEp {
    port: 9090
};

// Enable client code generation for this service.
@swagger:ClientConfig {
    generate: true
}
@http:ServiceConfig {
    basePath: "/sample"
}
service Hello bind helloEp {

    @http:ResourceConfig {
        methods: ["GET"],
        path: "/hello"
    }
    hello(endpoint caller, http:Request req) {
        http:Response res = new;
        res.setPayload("Hello");
        caller->respond(res) but { error e => log:printError("Error when responding", err = e) };
    }
}

Annotations

Name Attachement Points Data Type Description
ClientConfig service ClientInformation

Annotation to configure client code generation.

ClientEndpoint endpoint -

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

ResourceInfo resource ResourceInformation

Annotation for additional Swagger information of a Ballerina resource.

ServiceInfo service ServiceInformation

Annotation for additional Swagger information of a Ballerina service.

Records Summary

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

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

Model for Swagger 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

Model for service documentation definition.

Field Name Data Type Default Value Description
description string

Documentation description

url string

External documentation url

public type Encoding

Model for additional Swagger content type definition.

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

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

allowReserved boolean

Determines whether the parameter value SHOULD allow reserved characters

public type Example

Model for keeping Swagger 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 Swagger header definition information.

Field Name Data Type Default Value Description
required boolean

Is this a required header

discontinued boolean

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 ParameterInformation

Model for keeping Swagger parameter information.

Field Name Data Type Default Value Description
inInfo string

Where the parameter is located. Ex: query

name string

Parameter name

description string

Description of the parameter

required boolean

Is this parameter MUST be present in the request

discontinued boolean

Is this parameter deprecated

allowEmptyValue string

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

schema swagger:0.0.0:Schema

Parameter data type

public type ResourceInformation

Model for additional Swagger 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 swagger:0.0.0:DocumentationInformation

Additional documentation for this operation

parameters swagger:0.0.0:ParameterInformation[]

A list of parameters that are applicable for this operation

public type Response

Model for keeping Swagger response information.

Field Name Data Type Default Value Description
code string

Reponse code

description string

Response description

response string

Response content

headers swagger:0.0.0:Header[]

Response headers

examples swagger:0.0.0:Example[]

Examples for this response

public type Schema

Model for keeping additional Swagger schema information.

Field Name Data Type Default Value Description
format string

Data format as specified by Swagger data type

isArray boolean

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

Model for additional Swagger information of a Ballerina service.

Field Name Data Type Default Value Description
title string

Title of the Swagger definition

serviceVersion string

Version of the Swagger API

description string
termsOfService string

Service usage terms and conditions

contact swagger:0.0.0:Contact

Contact information for the exposed API

license swagger:0.0.0:License

License information for the exposed API

externalDocs swagger:0.0.0:DocumentationInformation

Additional external documentation

tags swagger:0.0.0:Tag[]

A list of tags used by the specification with additional metadata

security swagger:0.0.0:SecurityRequirement[]

Security requirements for this service

public type Tag

Model for Swagger service tag definition.

Field Name Data Type Default Value Description
name string

Tag name

description string

Tag decription

externalDocs swagger:0.0.0:DocumentationInformation

Optional documentation on the tag

public type requestBody

Model for additional Swagger request body details.

Field Name Data Type Default Value Description
description string

Brief description of the request body

required boolean

Determines if the request body is required in the request

example string

Example of the request body media type

examples swagger:0.0.0:Example[]

Examples of the media type

schema swagger:0.0.0:Schema

The schema defining the type used for the request body

encoding swagger:0.0.0:Encoding[]

Encoding and content type details