Learning Swagger.io (Part 1)

I recently studied and experimented with a few of the current features of Swagger.io...

In the past, I heard different people talking about using Swagger.io for vastly different purposes. I was confused. Some folks were annotating their source code and using Swagger to produce documentation for their REST services. Others were using Swagger docs to automatically generate server-side product code. Others said they were generating mobile client-side code from a Swagger doc. What was going on?

It turns out they were all right.

The basic concept of Swagger.io remains the same.  It's a simple standardized way to represent a REST interface in a document. However, there are now a significant number of tools packages available to produce and consume Swagger.io docs for various purposes.

References 

First, I found a few blog articles from PointSource which caught my interest. http://www.pointsource.com/blog/3-best-practices-for-api-development-with-swagger
and
http://www.pointsource.com/blog/client-side-swagger-support-for-angularjs

I also read a good portion of the Swagger spec:  https://github.com/OAI/OpenAPI-Specification

Name change

Swagger has been donated to the open source community and renamed to Open API Specification.

Getting started

I decided my first goal was to use the online Swagger Editor to define a simple hello world API, and then auto-generate a server-side instance and test it...

Using Swagger Editor

The Swagger Editor is an online tool:  http://editor.swagger.io/#/

I poked around with it a little while.  It's pretty straightforward.  The left panel is an editor where you enter the representation of the API.  The right panel is a live rendering of the Swagger docs created from the left panel.

Create the simplest API you can in the left panel.  Scroll the right panel up and down until you like everything.

Export your definition to a local file for safe-keeping by clicking the upper left tab: File-> Download YAML.

Here is my YAML file.  You are welcome to use it.

# This is an example Swagger API spec in YAML
swagger: '2.0'
info:
  title: Hello World API
  description: This is the exciting Hello World API
  version: "1.2.3"
host: helloworld.com
schemes:
  - https
basePath: /v001
produces:
  - application/json
paths:
  /healthcheck:
    get:
      summary: Returns a known response to indicate service status.
      description: The healthcheck endpoint returns status of the running service.
      tags:
        - User
      responses:
        200:
          description: General information about the running service.
          schema:
            type: object
            properties:
              cpu:
                type: integer
                format: int32
              message:
                type: string
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
        description: Error code.
      message:
        type: string
        description: Human-readable error message.

Auto-generating a server-side instance

My next step was to download a node.js server-side instance which implemented my API.

From the Swagger Editor, click Generate Server-> Node.js   It produces a zip file.  Download it to your machine.

Unzip the file.  Download the dependencies with 'npm install'.  Start the server with 'node index.js'.  Note that the server starts on port 8080 by default.

Confirm it works

The easiest way to confirm the endpoint works is to issue a REST request to it with cURL.  Notice it renders the variable names specified in the YAML, and adds dummy values to them.

Done

This completes the easy part:

• Manually defining a REST API using Swagger Editor
• Auto-generating a server-side instance in Node.js
• Verifying the server-side instance delivers the endpoint

I hope I get time to keep studying...