Automating API Code Generation

By CIOReview | Monday, October 24, 2016

APIs have lately gained lot of adherents, which is transforming into a pop culture for developers. However, when it pertains to generating API code, developers have a hard time due to the existing gaps in documentation and demands of product managers. APIs are effectual; however, building them is a gruesome task. Intricate details and information needs to be monitored carefully, because it’s easy for data to get mixed up in the process of flowing from product designer/ managers table to a documenter’s conditions, to a developer’s code.

This article will explore Swagger–a tool that can help keep code and documents aligned all the way through the app creation process. It enables individuals with adequate technical abilities define an API, produce documentations and generate the code to back it up. Swagger-enabled API delivers interactive documentation, discoverability and client SDK generation.

Online Swagger editor enables users to design API using YAML–a human-readable language akin to XML. Users can define paths by entering a string as an input that maps to a partial URL. Subsequently, the user can define the structure of input parameters and output info, implement any security that is required, and the user is ready to deploy.

Writing Specifications

JSON or YAML–either of these languages can be used to write the specifications. Consequently, users can make the swagger.json or swagger.yaml file. The online editor can be utilized for creating the file.

Too know more about the syntax for specifications users can refer swagger’s web page.

Ways to Use Swagger and the Development Workflow

1. Top Down Approach–API first approach

Steps to follow:-
(i) Use swagger editor
(ii) Write swagger definitions
(iii) Use swagger-codegen and swagger-UI to generate APIs

Users can start and write their API specification first. Established on this, the user can generate both JAX-RS stub resource classes and a client library for using the service. There is one more way in which the user could utilize the Swagger Editor for creating the specification, but for this, the user needs to learn the specification language.

When enterprises start with a new project with multiple teams from different departments, they have to commit to an API specification primarily. Thus, all the teams can start working directly without waiting for a service team. An innovative tool for this purpose is swagger-infector. It makes implementation of a JAX-RS server rooting on a given swagger file, since there is no requirement of JAX-RS generation step. The tool attends to the wiring and requests are redirected to business logic during runtime.

2. Bottom Up Approach–Service first approach

Steps to follow:-
(i) Develop JAX-RS resource classes using swagger annotations
(ii) Use swagger-core to automatically generate the swagger definitions
(iii) Using swagger-codegen and swagger-UI to generate client APIs and documentations

Users usually begin developing RESTful service by writing JAX-RS resource classes and then provide related extra documentation by adding Swagger annotations to the resource class.

As Philipp Hauer notes in his blog, Swagger annotations mostly start with the prefix “@Api*”.

Now, Swagger will process the annotated classes and generate the formal specification. Usually, HTML documentation will be formed in the same step for the API based on the specification. There are few ways to do that:

• Users can generate swagger specification and documentation during the maven build. This can be achieved using the swagger-maven-plugin.
• If the enterprise is using Dropwizard, they can use the dropwizard-swagger bundle, which will automatically generate the swagger specification and documentation depending on the classes when the service is starting and further publish both under URL’s. This way the user can ensure that the documentation and specification is up to date with service published.

Server and Client

The imminent feature that is discussed next is what makes the tool very unique.

Users can generate the code to deliver or consume API in almost any desirable language using the Generate Server and Generate Client menu options. This feature can save hours of gruesome programming. It also will aid the process by making the changes required which will occur during the lifetime of an API. The whole process conforms to the enterprises’ source control strategy when export feature is used to make a local text file. Users can publish the file, if they want, so other developers can integrate with the user’s data.

Writing an API code is an innovative task but a time-consuming one. Swagger can be utilized to design that API and publish the YAML, this will make it uncomplicated for the internal developers and it will also make it easier for the developers who wish to use your data.