ballerina/swagger package
Package overview
This package provides the following code generation capabilities to Ballerina:
- Generate the Ballerina code for a given Swagger definition.
- Generate the client stub for an existing Ballerina service at build time.
- 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 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 Swagger contact information.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
name | string | Contact name |
|
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 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 record
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 |
public type Header record
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 record
Model for service licence information.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
name | string | License name |
|
url | string | License url |
public type ParameterInformation record
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 record
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 record
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 record
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 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 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 record
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 record
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 |