Designing and Documenting a RESTful API Using Swagger


The prevalence of RESTful APIs is visible in a vast majority of web and mobile applications that we consume and — as API developers — that we code. They serve as a common interface that can be shared between web and mobile applications, and they allow us developers to reduce the number of codebases that we must maintain to support a wider range of applications. Given the impact of APIs in the industry, developers should take care to fully engage at every stage of the development lifecycle.

One of the most commonly overlooked steps in the development lifecycle is documentation. For me, it’s a task I inevitably put off as long as possible. Yet, it’s a critical piece of an application that, when done and done well, helps drive adoption. It would be a shame to invest hundreds or even thousands of hours into developing an API only to have potential users abandon it because they aren’t able to discover its capabilities quickly and easily.

This is where the beauty of Swagger comes in. By integrating your API specification with Swagger, you get the tools to design, build and document your API. This post will cover the Swagger tools available to design and document your API specification. I’ll save the build step using Swagger Codegen for a possible future post.


Why Swagger?

Swagger offers flexibility for developers on several levels.


Widely Adopted

Swagger provides a powerful framework of tools based on the Swagger Specification. This is an open-source specification that is the basis of the OpenAPI Specification (OAS). The Swagger Specification and suite of tools have become an industry standard for describing RESTful APIs and have been adopted by millions of developers and companies.


Programming Language Support

Swagger supports over 25 programming languages, so unless you’re coding in some eccentric language, Swagger probably supports your choice.


Feature-rich Framework

Swagger provides a complete framework of free and open-source tools that enable you to design, build and document your RESTful API quickly and efficiently.


Design With Swagger Editor

Swagger Editor is a browser-based tool that lets you quickly design your API using a straightforward YAML syntax. As you build out your API definition with the editor in the left pane, it’s rendered for you in the right pane, letting you immediately visualize your definition and easily identify errors.


Figure 1

Figure 1. Swagger Editor


Document With Swagger UI

Swagger UI is a feature-rich toolset that allows developers and API consumers to visualize and test the API without the need to code an application just to make the necessary web requests. It has become an industry standard, meaning consumers of your API are presented with a familiar interface. This familiarity translates into less time spent searching through your documentation, and more time getting to know your API and ultimately, hopefully, a higher adoption rate for your API!


Figure 2

Figure 2. Swagger UI



I’ve covered what Swagger is and why it’s beneficial to adopt. Now I’d like to take a closer look with a real-world example.


An Example Using JavaScript, Node.js, and Express

In a typical RESTful API project, you might design your API in a modular way that implements a /routes folder containing a single index.js file responsible for routing your API requests to the correct controller code.


Node App Without Swagger


/** ./server.js */
app.all('/api/v1/*', [require('./api/middlewares/validateRequest')]);
app.use('/', require('./api/routes'));

/** ./api/routes/index.js */
var router = require('express').Router();
var auth = require('../controllers/auth');
var customer = require('../controllers/customer');
var account = require('../controllers/account');
var admin = require('../controllers/admin');

// Public routes'/auth', auth.login);

// Must be authenticated to access these routes
router.get('/api/v1/customer', customer.getCustomers);
router.get('/api/v1/account', account.getAccounts);

// Must be authenticated AND properly authorized to access these routes
router.get('/api/v1/admin', admin.addUser);

Code Snippet 1. A Common RESTful API Routing Pattern


Note that the snippet above uses a middleware to handle authentication and authorization. With Swagger, you can continue to use your middlewares and Swagger won’t get in the way.


A Basic Node App Using Swagger

Using Swagger UI (for this example, we’re also using the Swagger-express-mw npm package), you can configure Swagger UI in your API server code and define your API specification in your swagger.yaml file.


/** ./server.js **/
var SwaggerExpress = require('swagger-express-mw');
var app = require('express')();
module.exports = app;

var config = {
    appRoot: __dirname

SwaggerExpress.create(config, function (err, swaggerExpress) {
    if (err) { throw err; }

    // install middleware


    var port = process.env.PORT || 10011;

Code Snippet 2. Defining Swagger UI in Your API Server


    # binds a127 app logic to a route
    x-swagger-router-controller: hello_world
      description: Returns 'Hello' to the caller
      # used as the method name of the controller
      operationId: hello
        - name: name
          in: query
          description: The name of the person to whom to say hello
          required: false
          type: string
          description: Success
            # a pointer to a definition
            $ref: "#/definitions/HelloWorldResponse"
    x-swagger-pipe: swagger_raw
# complex objects have schema definitions
      - message
        type: string

Code Snippet 3: swagger.yaml (note: some code removed for brevity)


Highlights of the swagger.yaml File

The following list highlights some of the key portions of the Swagger definition.

  • /hello:
    This definition specifies how users should be routed when they make a request to this endpoint.
  • x-swagger-router-controller: hello_world
    This line tells Swagger which code file acts as the controller for this endpoint.
  • get:
    This command defines the method being requested (GET, PUT, POST, etc.).
  • operationId: hello
    This command directs Swagger to the specific method in your controller to invoke for this endpoint.
  • parameters:
    This section defines the parameters of your endpoint. They can be defined as path, query, header, formData, or body.
  • definitions:
    This section defines the structure of objects used in responses or as parameters.


Why Should I Care?

The beauty of this process is that you don’t need a separate routing file and API spec definition file. Just define your API in swagger.yaml and the routing AND documentation are handled for you! To make defining your API even easier, you can use Swagger Editor to have a side-by-side view of your YAML definition and the resulting API documentation. It will instantly update to highlight any syntax or definition errors.


Figure 3

Figure 3. Quickly Identify Errors in Your API Definition Using Swagger Editor


Limitations of Swagger

The Swagger community has done a great job of putting together an excellent framework that just works well. I haven’t found many limitations in my experience with Swagger, but it does have a few:

  1. The Swagger specification doesn’t support nullable data types. The consequence of this is any fields you define as nullable won’t display in your model schema in Swagger UI. This limitation doesn’t prevent the use of nullable types, but it can create some confusion when you’re trying to discover your API definition.
  2. Swagger UI is pretty similar across implementations. I know, I just touted this as a benefit, and I believe it is. However, I can imagine a scenario in which a team would like to utilize the power of Swagger, but would like more control over the UI/UX. It isn’t impossible to do, but it requires quite a bit of re-engineering to do much more than update the skin of the UI.



Get out there and try Swagger! You’ll be up and running with very little effort, and building your RESTful API, along with its supporting documentation, much more consistently and efficiently.


Additional Resources


03 Apr 2017

Self-Service ETL


Self-Service ETL with Power BI


Recently, I’ve been using Microsoft’s Power BI heavily and am impressed with this solution as an end-to-end self-service business intelligence (BI) option. In addition, I’ve really come to appreciate the possibilities that self-service BI offers.


What is Self-Service BI?

Gartner defines self-service BI as “end users designing and deploying their own reports and analyses within an approved and supported architecture and tools portfolio.” The Data Warehousing Institute (TDWI) describes it as “[t]he facilities within the BI environment that enable BI users to become more self-reliant and less dependent on the IT organization.”

But Forrester Research notes there’s no standard definition of self-service BI.


What most experts on self-service BI do agree on is the value of removing IT departments that act as a barrier to users accessing and analyzing company data. Often, the access issue can be solved, but the analysis issue is more difficult, especially if additional transformations and manipulation are needed to answer business questions.


What is ETL? What is Self-Service ETL?

As anyone who performs BI or data analysis will confirm, getting data into the format needed for reporting and analysis is the most time-consuming part of data projects.


Coding skills or the use of data integration tools like SQL Server Integration Services (SSIS) may be needed. Extracting data from a source location, transforming it into the desired format, and then loading it into a destination location is referred to as Extract, Transform, Load (ETL). This process accounts for a substantial portion of BI projects.


Power BI really does stand out for its ability to pull data from a variety of sources and transform it for self-service users. Power Query is the component of Power BI that provides lightweight ETL for these users. Power Query uses Microsoft’s “M” language, which can be accessed by a user interface or written directly.


Power Query is only lightweight when compared to enterprise tools like SSIS; the average end user should find it quite powerful, yet easy-to-use. It can:


  • Fetch data from many different sources through its ever-growing list of connectors (see Figure 1).
  • Be used to filter and transform data, and to create and enrich data.
  • Build a “refreshable” process for the end user.


Figure 1. Connectors in Power BI.

Figure 1. Connectors in Power BI.



Again, Power Query uses Microsoft’s “M” language. If the user needs more functionality than what’s exposed through the Power Query Editor user interface, there’s the option to “tweak” a query using the Advanced Editor, or to just write a brand-new query using the Blank Query option.


The lightweight ETL capabilities within Power BI are a powerful addition to the self-service BI toolkit. For small and mid-size businesses, where skill sets may be limited, it provides a path to obtainable BI. For enterprises, it removes the IT barrier to timely reporting and analysis needed by the business and gives flexibility for the business to perform ad-hoc analyses. For both environments, it offers rapid prototyping that can be shared to convey business requirements with internal or external BI developers.


In future posts I’ll show how Power Query/“M” can be used to perform self-service ETL tasks.



In a world where data drives business decisions, great data visualization is crucial. Businesses today demand reporting dashboards that can assist with decision making and strategic planning.

Generating sleek and informative reports is not an easy task. They require careful balance between displaying a collection of information that provides real insight with having a simple, user-friendly dashboard design. To achieve this balance for my clients, I use parameters in Tableau. Dynamic visuals, strong aesthetics, and easy maintenance are just a few benefits of Tableau’s parameterized visuals.

Dynamic Visuals

Using parameters in Tableau dashboards allows end users to select a measure and level of granularity for a single visual using multiple data sets. For example, if a client requests both sales and profit values in a dashboard, there are several methods of accomplishing this.

One solution would be to create two visuals; one showing sales while the other shows profit. However, with parameters, you can have a single visual that includes both data sets with an option to choose whether to view sales or profits. We can take it a step further and provide the end user with the option to view the data for different time periods (weekly, monthly, yearly etc.).

Pavelblog_graphic 1


In some cases, it can become overwhelming when a dashboard contains multiple visuals of the same type. Therefore, consolidating visuals into a dynamic visual greatly increases the aesthetics of the dashboard by providing white space and additional capacity for visuals of different types. With that, Tableau does a great job of presenting parameter values to the end user and provides several options that will fit the dashboard layout such as single value list, or a compact list, among others.

It is crucial to understand how data is visualized on the dashboard. Stakeholders will appreciate the strong, user-friendly design they can easily manipulate and modify reports from which they can gain valuable insights.

pavelblog_graphic 2

Easy Maintenance

As business requirements change, so does the reporting dashboard. Dashboards that are dynamic, agile and can change at the pace of business are easier to maintain and update. Parameterized visuals assist with this. If an additional metric needs to be displayed in the same visual style, simply add data to the parameter values. Easily-maintained dashboards decrease my development time and may drive down time I bill to the client, since the hours required for dashboard revisions is lower compared to a less-dynamic setup.

pavelblog_graphic 3

If you need more help, Tableau offers video tutorials explaining parameters and other Tableau concepts.

Are you using parameters in Tableau? Where have you seen the most value in doing so?

campeau power bi blog

SSAS Tabular and Power BI are two cornerstones of Microsoft’s new generation of BI tools, and play quite well together out of the box. For these tips, I’ll assume you have a properly connected gateway up and running linked to a tabular model in Power BI, and that the model has been properly designed so none of this will look unfamiliar to anyone who has previously worked with a pivot table.



This blog was originally posted to the Piraeus Consulting blog on September 2nd, 2015 and may contain out-of-date information.

Depending on the insights desired, presenting data models as cumulative, rolling totals – as opposed to showing a Grand Total broken out over periods of time – can be an invaluable tool in analyzing key business decisions, spotting the difference between real trends and clear outliers, and crafting longer-term strategies.



This blog was originally posted to the Piraeus Consulting blog on November 24th, 2015 and may contain out-of-date information.

BI in Layers

This is an exciting and difficult time in Business Intelligence. The tools available are advancing at a breathtaking rate while best practices are changing equally as fast. While the tools promise to take in data and output insights, what that process requires can be somewhat vague at times. Usually, the programs are designed to tackle one of these four layers:

  1. Raw Data
  2. Data Transformation
  3. Data Model
  4. Visualizations

Oftentimes when businesses struggle to produce results from their BI strategy it is because they try to use one tool to accomplish everything, when the tool is really designed to tackle only one of the four layers.




This blog was originally posted to the Piraeus Consulting blog on February 22nd, 2016 and may contain out-of-date information.

For those who have followed my previous posts on the new Power BI application from Microsoft, you’ve probably already created some fantastic-looking visuals to tell the story of your data. If the art of tapping into a variety of sources, editing your dataset on the fly, and customizing your charts and graphs is old news, then let’s look at how you can manage your Power BI content in a whole new way. By this, I mean sharing your impressive visualizations through a new group workspace. Using this workspace, you can add granular membership and control permissions at the user level. While we’re at it, we will also look at how to migrate existing reports to this space and how to update and manage them through content packs.



This blog was originally posted to the Piraeus Consulting blog on March 14th, 2016 and may contain out-of-date information.

Tableau Vizable Piraeus Consulting

At their October user conference, Tableau unveiled their new visualization app: Vizable. Vizable is built for the iPad and promises to empower non-professionals to represent spreadsheets visually and to manipulate data in easy-to-use charts and graphs. Dave Story, Tableau’s Vice President of Mobile and Strategic Growth, positioned this app as a handy tool for the masses, saying, “It’s for anybody who has a tablet, data and questions.”



This blog was originally posted to the Piraeus Consulting blog on May 31st, 2016 and may contain out-of-date information.

Recently, I attended a brown bag where one of our senior consultants, let’s call her Michelle, outlined the basics of conceptual and logical data models. I’m nowhere near Michelle’s level of technical expertise, but I still found her presentation to be both informative and intriguing. By the time it was over, I felt compelled to give myself an exercise in conceptual data modeling.



This blog was originally posted to the Piraeus Consulting blog on August 21st, 2014 and may contain out-of-date information.

As BI professionals, we rarely lack software to support our work, but we often do lack information relevant to helping us select the right software for the right need.

In its 2013 rollout of Power BI, Microsoft introduced a suite of self-service BI products integrating with existing analytics tools, and yet the rollout left some teams seeking to supplement Power BI with other products.



In mid-November, Beyondsoft achieved the designation of Adobe Analytics Specialized Partner in the Americas at the Community level. Specialized Partners are known as the “best of the best” in the Adobe Partner ecosystem, and have proven their capabilities through rigorous certification testing. While over 400 Adobe Partners are certified at the Community level, only 17 of them have achieved Specialized Partner status, which reflects a high degree of quality and consistency in delivering successful customer implementations.