Manage Learn to apply best practices and optimize your operations.

Is there a way to automate API code generation?

As useful as APIs are, developers still struggle to create them due to lapses in documentation and specs. Brad Irby explores a tool that can help 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.)

Instagram API code
Figure 1. Using Swagger to review the Instagram API code.

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.

defined paths
Figure 2. A look at one of the defined paths.

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).

Media definition
Figure 3. A partial view of the Media definition.

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.

auto generated documentation
Figure 4. Automatically generated documentation.

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.

generate server
Figure 5. Using the Generate Server and Generate Client options.

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.

Next Steps

Defining API economy

How to query data directly from an API

Learn why an API strategy isn't just for developers anymore

This was last published in October 2015

PRO+

Content

Find more PRO+ content and other member only offers, here.

Essential Guide

API integration tutorial: Latest trends and strategies

Join the conversation

6 comments

Send me notifications when other members comment.

By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy

Please create a username to comment.

What is the API code generation process like in your organization?
Cancel
@mansillaDev - nice tip! I didn't know about that one
Cancel
A comparison of the tools for automatic code generation (including Swagger CodeGen) can be read here:
apievangelist.com/2015/06/06/comparison-of-automatic-api-code-generation-tools-for-swagger/
Cancel
Swagger is certainly a nice tool to use when working on APIs. I’d like to see some development done on a Swagger extension to help with the generation of test scenarios based on the YAML.
Cancel
@mcorum, that's a great idea. Have any extra time on your hands for that? :)
Cancel
Here is more realistic comparison from John Davidson by looking at the issues with the auto-generated SDKs (https://blog.jongallant.com/2015/09/api-sdk-generators.html#comment-2671838966)

######
1) AutoRest:

It is pretty active, open-source but the auto-generated SDKs lack some important features such as authentication: https://github.com/Azure/autorest/issues/980#issuecomment-214807833

2) APIMatic:

Given that it's not open-source, a simple search in GitHub shows some low-level issues (failed to compile, etc) with the SDKs generated by APIMatic: https://github.com/search?o=desc&q=apimatic&s=updated&type=Issues&utf8=%E2%9C%93

3) Alpaca

Last commit was Apr 15, 2015 so seems like it's no longer active.

4) RESTUnited

It uses SwaggerCodegen as the code generator and also generates documentation and hosts it for you.

5) Swagger-Codegen:

It is also very active, open-source but the fact that it's too active means a feature request or issue report may take a while to get a reply from the team as they seem to be very busy.

My suggestion:

If you're a fanboy of MS technology, go for AutoRest, otherwise Swagger-Codegen.
######
Cancel

-ADS BY GOOGLE

SearchSoftwareQuality

SearchCloudApplications

SearchAWS

TheServerSide.com

SearchWinDevelopment

DevOpsAgenda

Close