How to Document an Existing API Using Swagger

How to Document an Existing API Using Swagger

by Jun 1, 20170 comments

A few months ago, I jumped into an exciting project with my teammates at Shockoe. My expertise was needed for testing and debugging, which led me to begin working with the middleware API. In this particular case, the project presented new challenges, APIs that had already been set up by a client and the fact that this was an ongoing project, which meant that it was still changing and being updated regularly.

Adding features to the project required new resources and endpoints. Updating how error messages were handled required updating API responses and, after a certain point, enough changes had been made that the documentation had to be remade.

I came across two popular resources for documenting APIs: Swagger and RAML.

RAML takes a top-down approach to defining APIs, which means that you first define what your methods will be and then how they will work. By using a methodology that involves defining the system and providing the details later, this works well while developing an API since it goes alongside the developing mindset.

On the other hand, Swagger uses a bottom-up approach, defining each method one at a time. In my case, I decided to use Swagger because this methodology works better when documenting an already existing API. Swagger basically allows you to work through each API call and document as you go.

Swagger uses JSON objects to describe its API request and responses. For example, an API with a pets endpoint for a GET request could look like the example below, with a separate items object defined later in the document to increase readability.

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "produces": [
        "application/json"
      ],
      "responses": {
        "200": {
          "description": "A list of pets.",
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/pet"
            }
          }
        }
      }
    }
  }
}

Since I had already been using Postman to test each call, I had a quick way to go through each call, document the request and response, and move on to the next step.  Because the API only returned JSON the similarity between formatting for the response and the swagger response documentation led me to create a simple conversion program. This allowed me to easily input the response from an API call and output a properly formatted swagger documentation for it.

function convertToSwagger(item){
  var string = '';
  if(item === null){
    string += '{\n'+'"type": "string"\n'+'},';
  } else {
    switch(typeof item){
      case "string":
        string += '{\n'+'"type": "' + typeof item +'",';
        if(item.length > 150){
          item = item.substring(0,150);
        }
        if(item.includes('"')){
          string = string.slice(0,-1);
          string += '\n'+'},';
        } else {
          string += '\n';
          string += response ? '"example": "' : '"default": "'
          string += item + '"\n'+'},';
        }
        break;
      case "number":
        if(Number.isInteger(item)){
          string += '{\n'+'"type": "' + 'integer' +'",';
        } else {
          string += '{\n'+'"type": "' + 'number' +'",';
          string += '\n'+'"format":"float",';
        }
          string += '\n';
          string += response ? '"example": ' : '"default": '
          string += item + '\n'+'},';
        break;
      case "boolean":
        string += '{\n'+'"type": "' + 'boolean' +'"\n'+'},';
        break;
      case "object":
        if(Array.isArray(item)){
          string += '{\n'+'"type": "' + 'array' +'",';
          string += '\n'+'"items": ' + convertToSwagger(item[0]).slice(0,-2) + '\n'+'},';
        } else {
          string += '{\n'+'"type": "' + 'object' +'",';
          string += '\n'+'"properties": ' + '{\n' + createProperties(item) + '\n'+'}\n'+'},';
        }
        break;
      default:
        // do nothing
    }
  }
  return string+"\n";
}

At this point the process became simple, look up the API request, document the new path in Swagger (which can be made easier by copying an existing path and changing the different fields), make a request to get a sample response, put the response in the converter and copy it over to the swagger file. From here, I was able to quickly finish documenting the API and set up a process to easily keep it updated or document another finished API.

Documenting a project can seem daunting when you need to do it all at once, but it is still a very important part of the process. In the end, I found Swagger to be a great API document that was easy to use for my project needs. I was able to quickly pick it up and get started. Adding each method was simple to do after the first one and it helped give an overview of all the available methods while showing example requests and responses along the way. I hope this helps you when you find yourself documenting existing APIs, leave us a comment if you have any questions or insight on how to use Swagger.

Editor: Interested in learning how our developers debug applications? You can read more from our last week’s blog. For our blog on API Description Language for the Enterprise click here.

Want to stay connected on all things mobile?

 

Sign up for the Shockoe newsletter and we’ll keep you updated with the latest blogs, podcasts, and events focused on emerging mobile trends.

 

David Vieth

David Vieth

June 1, 2017

David is a native iOS developer who’s recently been working in Angular and Node. His interest in programming, love for solving puzzles, and focus on efficiency is what led him to being a mobile application developer. Although his main focus is front-end UI and API integration, he’s always willing to branch out and learn something new.

More like this delivered right to you:

Sign up for our Newsletter to get our latest posts plus invitations to our events and access to future whitepapers.

Related Posts

Seeing the Member Experience in a “User-Experience” World

Seeing the Member Experience in a “User-Experience” World

In the world of product development, we are often always saying “user” _______. User-centered design, user analytics, user personas, user journeys, etc, etc.It’s a term that holds importance because it is a genuine focus on the end-user experience.  It’s also often...

7 Tips for Utilizing Amazon Alexa to Engage with Customers

7 Tips for Utilizing Amazon Alexa to Engage with Customers

Amazon first released Alexa virtual assistant and smart speaker Echo in late 2014. An in-home virtual assistant is an impressive tool, but creating a seamless user experience with it can be a challenge. So how do companies overcome this challenge? What engagement can...

Ready to drop us a line?