Channels ▼

Open Source

Swagger All The Way Into RESTful Services

Swagger is an emerging developer tool barely gracing the newswires. This new language-agnostic open-source specification is a complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

The Swagger framework claims to be able to simultaneously solve server, client, and documentation/sandbox needs.

It allows both developers and non-developers to interact with the API in a sandbox UI that gives insight into how the API responds to parameters and options.

According to the development team behind Swagger, its "overarching goal" is to enable client and documentation systems to update "at the same pace" as the server.

The documentation of methods, parameters, and models are tightly integrated into the server code, allowing APIs to always stay in sync.

Swagger was developed for Wordnik's own use during the development of and the underlying system. Wordnik shows English language definitions from multiple sources, so users can see as many different takes on a word's meaning as possible.

The Swagger team calls out a couple of caveats and says that it does not currently include a suggestion for supporting multiple API versions from a client or server point of view — versioning information (both of the spec and the underlying API implementation) are declared.

"It does not tell you how to write your APIs. For example you can choose to delete an object from your system either by an HTTP delete operation or via HTTP GET with query param. While being a good, RESTful citizen is encouraged (and rewarded by an effective API sandbox client), it is not a prerequisite to use Swagger."

The team also says that Swagger is not trying to solve all problems for all APIs and that there will be use-cases that fall outside of the Swagger specification.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.