How to Document an Existing API Using Swagger

How to Document an Existing API Using Swagger

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.

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.

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.

Interested in what it would take to kick off your project?

Our experience and core services include strategy & transformation, user experience & design, mobile application development, and API management.

Debugging Titanium Applications using Safari Web Inspector

Debugging Titanium Applications using Safari Web Inspector

Debugging is one of the most frustrating aspects of software development of any kind – it is also one of the most essential. Finding a malfunction can be time consuming; therefore, it is important to have effective tools that can decrease your debugging time. For Titanium, most of my debugging consisted of log statements and alerts. While this method can be useful, it can also be a little time consuming to rebuild and to log a different variable, collection or model.

One of my coworkers saw me using this log for debugging and suggested an alternative: using Safari Web Inspector. I was very surprised at how easy it was to set up and how effective it can be throughout the process. This one line is all you need to add to your “tiapp.xml” file in your project:


under the <iOS> flag. Unfortunately, this method only works on an iOS simulator. Once you have updated your tiapp.xml, build your project and navigate to the page you would like to inspect. Next you will need to open Safari; if the develop tab isn’t visible you will need to follow a couple extra steps:

Select the Safari tab from that dropdown navigate to preferences then check “Show develop menu in bar.” After the Develop tab is visible you will open the Simulator option and then select JSContext.

This is where all the magic happens. The files where breakpoints can be inserted will be visible on the left panel of the screen. Breakpoints are very convenient for stepping through your code and seeing exactly what is happening. I suggest opening the right panel when the breakpoints are hit. This is where you will find local variables and can also add Watch Expressions. Watch Expressions is the place where you can add the variables that you would like to keep an eye on. You will be able to see and follow each variable through every step of your code.

The bottom console is also a very helpful aspect of this debugger. I use this for taking a look at any model or collection to inspect in detail what they contain. This has been a lifesaver for me. It makes it easy to investigate exactly what is going on with any unexpected behavior with your models or collections.

The safari web inspector has it’s problems and will, from time to time, crash the app – but overall this tool has helped me immensely debugging my titanium apps. It makes it so effortless to nail down exactly where the problem lies. As much as we all want to have flawless code without bugs, they will appear every once in awhile. However, this tool can save you from the frustration those bugs can cause. As I stated before, it is very easy to set up, so jump in and play around with it a bit. Have any questions or comments? Feel free to share your your tricks for debugging. Also, you can find our latest apps and check out our work here.

Editor: In case you need to know other ways we used to debug Titanium Apps, please also check Appcelerator Titanium iOS Debugging with XCode or Rapid Titanium WebView debugging with Chrome Developer Tools


Interested in what it would take to kick off your project?

Our experience and core services include strategy & transformation, user experience & design, mobile application development, and API management.