Is there a way to automate API code generation?

APIs have become very popular, but developers still struggle when it comes to generating API code due to gaps in documentation and product manager demands. In this article, I explore how Swagger can help keep documents and code aligned throughout the app creation process.

So, we all agree that APIs are wonderful, but building them is tough. Many details need to be kept track of, and it's easy for those details to get mixed up when transitioning from a product manager's idea to a documenter's specs to a developer's code. I can't help you with the idea to documents phase (unless you have a product manager that can code), but keeping docs and code in sync is much easier if you use Swagger.

Swagger is a tool that lets anyone with decent technical skills define an API, generate documentation and even generate the code to support it. Using the online Swagger editor you design your API using YAML, a human-readable XML-like language. Define endpoints (called paths) by typing a string that maps to a partial URL. Then define the shape of the input parameters and output data, any security you want to implement, and you are ready to go.

One of the samples the Swagger editor has for you to review is for the Instagram API (Figure 1). (If you go to the editor and choose File->Open Example, you can choose from several other examples as well.)

Among other data in Figure 1, you see that there are eight paths defined (the ones starting with a single quote are commented out and I clicked on the small diamond next to the line number in order to collapse the nodes for readability). When you open one of those paths (Figure 2) you can see that it requires the GET HTTP verb. You can read the description and see that it requires three parameters. Upon success (a response 200), it returns an array of objects defined in the Media definition shown near the bottom under definitions.

Likewise, you can open the definition for Media and see the details for properties of this object, including embedded objects (I show only part of the Media definition in Figure 3).

Defining the API with the Swagger editor is convenient, but it is no easier to use than other tools. However, in the right side panel of the editor, HTML documentation is generated automatically for the API that is described (Figure 4). The documentation is quite complete, pleasing to read and offers a way of trying out the described API call. Clicking the "Try this operation" button at the bottom allows you to enter the parameters, make the call and view the results.

Now for the coup de grâce that makes this tool so useful. Using the Generate Server and Generate Client menu options (Figure 5), you can generate the code to provide or consume this API in nearly any language you like. This API code generation tool alone can save hours of tedious programming, not to mention the help it provides while making the many changes that will occur over the lifetime of your API. Also, the whole process fits neatly into your source control strategy when you use the export feature to create a local text file. You also can publish this file so other developers can easily integrate with your data.

Writing API code is a wise but time-consuming effort. Designing that API with Swagger and publishing the YAML can make it easier on your internal developers, as well as easier on the developers that wish to consume your data.