Super Cool Feature for your Ballerina service from Ballerina OpenAPI tool
If you are extreme in API development, I do not doubt your consciousness with OpenAPI. OpenAPI is an API description format for REST APIs. It will describe your entire APIs and be documented with the formatted specification. You can use this specification for generating mock service with your coding language. How cool the ballerina language also has this capability. you do not need to spend some time on coding by yourself. In ballerina 1.0.2 version has been released with the super excellent feature as Ballerina OpenAPI Tool. Through this tool, you can generate mock services given by the open API specification.
OpenAPI Tool can do many functionalities making your coding life easy. Those are generating mocking ballerina services and clients through a given specification and generating OpenAPI contract for your given ballerina service file.
Momentarily we are addressing here the one cool feature of the OpenAPI tool, It is none-other than OpenAPI validator compiler plugging. It is available with all the ballerina 1.1.x. and 1.2.x, Swan Lake versions.
Through enabling this compiler plugin you can validate your OpenAPI specification against the ballerina service and Ballerina services against the OpenAPI specification. Before moving to a deeper explanation, I will add the OpenAPI annotation with its attributes here (Figure 02).
This annotation automatically created in the ballerina file once you have created the ballerina service file using OpenAPI specification.
Let’s go through all the attributes one by one.
- Contract (Required) :
This is the required attribute that you need to give the input to your annotation. Here, you need to provide a path to the OpenAPI contract as a string and the OpenAPI file can either be ‘.yaml’ or ‘.json’. According to the given OpenAPI contract it will validate your service by checking every resource function with it parameters and paths.
- Tag (Optional) :
This is not a required attribute. When you need to validate only for some tags instead of all the operations in your spec then you can add tags to the string array as inputs . The compiler will only validate resources against operations, which are tagged with a tag specified in the list.
Example : tags:[“pets”, “list”]
- Operations (Optional):
This is all so not a required attribute. If you need to only validate for a given operation list then you can provide operations with a string list that you need to validate. If not specified, the compiler will validate resources against all the operations defined in the OpenAPI contract. If both tags and operations are defined, it will validate against the union set of the resources.
Example : operation:[“listPets”]
- ExcludeTags (Optional) :
This feature is for users to store the tag. It does not need to be validated. Same as tag attribute you need to provide all the excluded tags in a string list. This attribute you can use when you have few tags to exclude rather than validate tags. At the same time, the “excludeTag” and “Tag” cannot store and the plugin will generate warning messages regarding it.
- ExcludeOperations (Optional) :
Same as the excludeTags attribute , This feature is for users to store the operations that do not need to be validated. You need to provide these operations with a string list. At the same time, the ‘excludeOperations’ and ‘Operations’ can not store and they will generate warning messages. Tag feature can store with ‘excludeOperations’, that time all the tag operations validate except the exclude operations.
- FailOnErrors (Optional) :
Last but not least attribute :) is failOnErrors. If you need to turn off the validation, add this into the annotation with the value as false. Its default value is true. When you need to turn on the validator you don’t need to enable this by adding the attribute. Only you need to use this for turning off the validation.
These are the attributes you can use with the compiler plugin.
Considering the service received from this plugin. This plugin will help ballerina users to find out the missing parameter, type mismatching of the parameter in the ballerina resource concerning its OpenAPI spec operations through Diagnostic log errors. This will let users know undocumented operations and resources in the service file and OpenAPI spec.
Try to use the ballerina OpenAPI compiler plugin with your ballerina service that is generated using OpenAPI spec. It will never let you do a mistake by missing service and parameters. :)
Enjoy this article, hope to come with the next article with another one of the cool features in Ballerina OpenAPI tool. Thank you all …! :)
Please refer the below reference for further details about Ballerina OpenAPI Tool.
For ballerina Swan Lake : https://ballerina.io/swan-lake/learn/using-the-openapi-tools/
For ballerina 1.2.x : https://ballerina.io/learn/using-the-openapi-tools/
