In this series of blog posts we’ll help you dive into Swagger, understand what it is all about and how you can use it to take your APIs to the next level. Each post will cover one of these aspects.
Let’s talk about the problem: We have an API that we want to document. Specifically, a REST API (we’ll get into what “REST” means here in a bit).
We can maintain a document with that information or an HTML website, or even have it generated by some tool from our code. The downside to this approach is that we need to keep it maintained manually (or via a semi-automatic process) and, while it is human-readable, it’s not really machine-readable.
Another approach is to use WADL, which can be generated by some tools. In this case, it’s machine-readable, but definitely not human-readable. Also, writing a WADL manually is a tedious process.
Seeking out a simpler solution for both made Swagger come to life. Swagger is a set of rules (in other words, a specification) for a format describing REST APIs. The format is both machine-readable and human-readable. As a result, it can be used to share documentation among product managers, testers and developers, but can also be used by various tools to automate API-related processes.
When we say REST, we don’t necessarily adhere to the RESTful rules. We refer to the basic concepts behind REST APIs. While WADL covers pretty much any possible API design at the cost of complexity, Swagger aims to cover the more common design patterns while being simpler to write and use.
In our latest iteration, Swagger 2.0, we’ve made the format acceptable in both JSON and YAML, to make it even easier to edit.
To help you understand what Swagger looks like, take a look at the following example:
swagger: "2.0"
info:
version: "1.0"
title: "Hello World API"
paths:
/hello/{user}:
get:
description: Returns a greeting to the user!
parameters:
- name: user
in: path
type: string
required: true
description: The name of the user to greet.
responses:
200:
description: Returns the greeting.
schema:
type: string
400:
description: Invalid characters in "user" were provided.
In the example above we describe a simple “Hello World API”. It has a single URL exposed - “/hello/{user}”. “user” is the single parameter to the API, defined as part of the path, and we say it’s a string. We also describe the successful response, and mention it’s a string as well. A generic 400 error can be received if the “user” contained invalid characters. You can also see that throughout the operation itself we provide additional documentation.
That’s pretty much it - that’s Swagger in a nutshell. The Swagger Specification is available for everyone to read at http://swagger.io/specification or read this Swagger Tutorial. It includes information on how to define paths, parameters, responses, models, security and more. The Swagger Specification itself is open source and available under ASL 2.0.
In upcoming blog posts, we’ll cover how to get started with Swagger in your project, how it fits into the general API lifecycle and the tools that are available out there, both open source and commercial.
If there are any specific aspects of Getting Started with Swagger you’d like to see us cover in this series, feel free to reach out to us and request - we’ll do our best to provide the information.