The Value of Specification First Development Using Swagger

The explosion of public facing APIs such as those provided by Twitter and the New York Times have changed the way programmers make software. Today, it is not atypical for a programmer to create applications that are essentially an aggregation of data and services provided by a variety of public APIs. Yet, as the need for APIs grows, so does the need for workflows that streamline the development process to make them. The days of making it up as you go along are coming to a close. The days of Specification First Development are coming, and for many shops they're here already. Specification First means that all work emanates from an ever evolving, but controlled specification. This includes coding, documenting, and enhancing software. Although some fear that Specification First will remove speed, creativity, and innovation from the practice of making software that counts, I am here to tell you differently. Specification First makes it possible to easily and accurately publish inventive APIs that are easy to consume and easy to maintain. Specification First does not hinder development; it empowers development.

Allow me to elaborate, but before I do, let me share something with you. I used to be of the camp that believed that specifying software slowed things down. I took to heart the part in the Agile Manifesto that says, working software over comprehensive documentation.

In the old days of making software, a high ranking engineer or business analyst wrote the specifications and then we coded to that spec. It was laborious effort that involved hand written specification followed by hand written code. Over time, the tools for making specifications evolved so that some code generation took place. But you could still drive a truck in the space between writing specification and having working code. When it comes down to spending money, back then, I would take the code every time. But that was then and this is now. What changed my thinking? Swagger.

Swagger is an open source specification for creating APIs. Swagger defines a hierarchical structure for specifying an API. The structure you define can be expressed in YAML or JSON. Swagger allows you to define your API specification with a high degree of detail. Of course, you can define endpoints and the HTTP method to use against the given endpoint. But, there is more. You can specify the parameters required by an endpoint, declaring if a parameter goes in the endpoint path, as a query string or is embedded in the body of the request to the API. Also, you can define special data structures that you want to submit in the request or return in the response from the API. Swagger makes it so you can provide a description for every aspect of your specification. And, that description will turn up in documentation later on, should you use tools that allow you to generate code and documentation from a single specification written in the Swagger format.

Listing 1 shows an excerpt from an API specification written according to Swagger. The excerpt defines a HTTP GET call to an endpoint, /{alphaChar}, WHERE {alphaChar} in a parameter defined in the path of the endpoint.

"/{alphaChar}": {
   "get": {
      "summary": "gets an alphaSquare",
      "operationId": "getAlphaSquare",
      "description": "get an alphaSquare as defined
         by the parameter, {alphaChar}\n"
      "parameters": [{
         "name": "alphaChar",
         "in": "path"
         "description": "The alpha character upon
            which to retrieve the square",
         "required": true,
         "type": "string"
      "tags": ["AlphaSquare"],
      "responses": {
         "200": {
            "description": "the requested alphaSquare",
            "schema": {
               "$ref": "#/definitions/Square"
         "default": {
            "description": "Unexpected error",
            "schema": {
               "$ref": "#/definitions/Error"

Listing 1: An API endpoint defined according to the the Swagger specification in JSON format

To be Swagger compliant means that your YAML or JSON is constructed according to the way Swagger says your API specification needs to be represented. Yes, Swagger has rules about how the specification is to be structured, but once you get the hang of it, you'll enjoy a great deal of freedom when creating your API. The folks who created Swagger know what they are doing.

As I said, in the old days the tools for doing specifications were not that good, and auto generating code from a specification was still evolving. Today, you can use a site such as SwaggerHub to create a Swagger compliant API specification in YAML or JSON and then generate server code tht supports the API you created. (Please see Figure 1.)

Figure 1: You can use a tool such as SwaggerHub to create functional code and accurate documentation from a common Swagger compliant code specification.

Yes, you do have take some time getting the hang of the Swagger Specification and yes, you do have to add implementation behavior to the code you auto generate. But, it's a small price to pay for getting API code that is predictable in structure as well as getting the depth of documentation you need for others to use your API. When it comes to programming using an API, accurate documentation is everything. An API that can't be used, ain't.

Riddler: A Demo Application Specified Using Swagger

The details of the nature and use of Swagger are a bit beyond the scope of this article. However, to help you out, I have created a sample application named Riddler. Riddler publishes a single endpoint that provided a riddle question and answer.

Riddler is a NodeJS application that was specified according to the Swagger 2.0 specification. The code and documentation for Riddler was generated from the SwaggerHub Web site. Also, I used SwaggerHub to validate that the JSON I wrote to specify Riddler was Swagger 2.0 compliant.

You can download the project from GitHub.

You can view the Swagger specification project for the application on SwaggerHub.

Everything Emanates from the Spec

At the enterprise level, just having a tool that allows developers to easily create API code and documentation based on a common specification is not enough. You need to have a workflow process to make sure everyone is rowing in the same direction. Otherwise, you are in Development Hell.

Development Hell is a place where a developer adds an endpoint, or changes an API endpoint request/response definition and doesn't inform those responsible for publishing documentation that the API has changed. Then, one day those depending on the API to get work done wake up to a bunch of broken code and have no idea about how to fix the problem because the endpoints defined in the API do not match the documentation. At best, the company publishing the API is the subject of flame and ridicule on the Internet. At worst, customers flee.

Specification First addresses the need to keep code and documentation in sync always. As mentioned above, the premise of Specification First is that all code and documentation emanates from a common Swagger 2.0 compliant API specification expressed as either YAML or JSON. Thus, when it comes time to update an API, the first place anyone goes is to the specification. (Please see Figure 2.)

Figure 2: The workflow for Specification First is simple and easy to adopt.

Change is made in the spec and then the code is regenerated along with the accompanying documentation. (Please see Figure 3.)

Figure 3: A tool such as SwaggerHub allows you to create interactive API documentation that is derived from the same Swagger specification you'll use to create your base code.

Now you may ask, when I regenerate, won't the existing code base be wiped out? The answer is, not if you are careful. The code generated under a tool such as SwaggerHub is the base code only. No implementation logic is generated. Implementation logic is the work of developers. Thus, when you go about Specification First, you need to make sure that the application code is structured in such as way that the operational entry point that is bound to a given endpoint is separate from implementation logic. The way you do this separation will vary according to the language/framework you use. SwaggerHub supports code generation in NodeJS, Spring-MVC (Java), Sinatra (Ruby), Asp.Net 5, and Silex (PHP), to name a few. When you design an application architecture that has a strong separation between API endpoint entry code and implementation logic, you'll be able to maintain the integrity of your code after any regeneration event with minimal tweaking.

Putting it All Together

As I mentioned at the beginning of this piece, the number of applications that depend on public APIs accessed over HTTP is growing every day. Programming using an API based on REST is a way of life. Thus, the way people program is changing, too. Today, there are a number of software shops that do not write any UI code. Their bread and butter is publishing APIs.

More applications will be consuming more APIs more often. And, as the appetite for an API grows, the need to make modifications to those APIs quickly and communicate those changes accurately to the user base becomes paramount. It's no longer just about getting the bits out there. You need to get the bits and docs out there at the same time. Specification First is a practice that, if followed vigilantly, will allow you to ensure the synchronous publication of code and documentation. Having API code and documentation emanate synchronously from a single, common specification makes delivering APIs continuously not only possible, but easy. Specification First will not slow you down. It will speed you up, maybe faster than you ever imagined.

About the Author

Robert Reselman

Bob Reselman is well known technology writer and software developer. He as written numerous books and articles about software and the making of software. Also, Bob is part of the technology cartooning duo, ROELBOB. You can view their work at: Bob lives in Los Angeles, CA with his wife, the musician Arlo Zoos and his pet, Itchy the Dog.

Related Articles


  • Writer of this article

    Posted by Bob Reselman on 05/27/2016 08:14am

    I need to make an addition to the article. I forgot to draw attention to using the property, x-swagger-router-controller to define name of the Javascript file that represents to the controller that contains the method (operationId) to which is bound to the HTTP method of the given path. Like so: "get": { "description": "Gets the scoreboard of the current game", "summary": "Gets a scoreboard", "operationId": "getScoreboard", "x-swagger-router-controller": "MyGameController", "tags": [""], "security": [{ "oauth": ["read:scoreboard"] }], "responses": { . . . In the example above the controller is the file, /controllers/MyGameController.js and the method executed against the GET of the path is getScoreboard(). Swagger expects controllers to be in the directory, /controllers. Here is a nice piece that provides more details:

  • Great contents

    Posted by Ashish Gandhi on 05/23/2016 06:55am

    There are also now some tools and framework (Nuget packages) available, which allows to create the automatic documentation of swagger to keep it always updated. I am using NancyFx, for creating the REST APIs and using Nancy.Metadata.Swagger, which helps creating an automatic documentation of the API to keep the documentation always upto date. This is same like the documentation created for the class library and other code using a tool like SandCastle. Overall, Bob, you are always and would be the person i would like to be in the world of technology. Thanks a lot for sharing the knowledge with us.

    • Writer of this article

      Posted by Bob Reselman on 05/27/2016 08:15am

      Thank you for your kind compliment.

  • Great article.

    Posted by Aaron Stanley King on 05/17/2016 01:08pm

    I like the article. Sometimes I can't write the spec first, especially on existing systems but I like the documentation of Swagger. I also like apiDoc. It's nice with Node.js Express APIs.

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

Most Popular Programming Stories

More for Developers

RSS Feeds

Thanks for your registration, follow us on our social networks to keep up-to-date