Wilson Mar bio photo

Wilson Mar


Email me Calendar Skype call

LinkedIn Twitter Gitter Instagram Youtube

Github Stackoverflow Pinterest

It does your job. And helps others to do your job.

US (English)   Español (Spanish)   Français (French)   Deutsch (German)   Italiano   Português   Estonian   اَلْعَرَبِيَّةُ (Egypt Arabic)   中文 (简体) Chinese (Simplified)   日本語 Japanese   한국어 Korean


What is Swagger?

Swagger Core is a Description Language (DL) for REST APIs. It provides:

  • a blueprint of layout,
  • a contract,
  • metadata, and
  • human-readable documentation.

The goal of Swagger is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

In other words, Swagger’s objective is to be a complete framework for describing, producing, consuming, and visualizing RESTful web services for developers to fully program clients calling them.

Swagger removes the guesswork in calling the service. This enables Swagger CodeGen to generate client code for different programming languages.

Swagger removes a barrier to enterprise adoption of REST API by making a larger number of REST APIs governable, shareable, and human-readeable.[1]

Who built Swagger?

Swagger originated from folks at Wordnik.com (the on-line English dictionary) by Reverb Technologies (helloreverb.com) which was absorbed by Inform.com, now a part of MongoDB. The old URL http://github.com/wordnik/swagger-core/wiki now redirects to http://github.com/wordnik/swagger-core/wiki.

On March, 2015, the testing company SmartBear acquired from Reverb the swagger.io website and SwaggerHub.com which provides an instance of swagger on a free platform for teams to collaborate on and coordinate across the entire workflow of an API’s lifecycle. SwaggerHub includes connectors for GitHub, DockerHub, and Ready! API. The site leverages a centralized definition to enable teams to work together to iteratively design, build, document, and manage an API.

The spec

On January 1, 2016, the Swagger Specification at version 2.0 was transferred to the Open API Initiative (OAI), and renamed to the OpenAPI Specification. To avoid confusion, many now refer to the spec as “Swagger (OpenAPI) 2.0”.

https://github.com/swagger-api is the group maintaining

  • swagger-core
  • swagger-spec
  • swagger-ui
  • swagger-codegen

PROTIP: Many prefer the visual spec at http://openapi-specification-visual-documentation.apihandyman.io (on Chrome browser) by Arnaud Lauret, the API Handyman.

Spec Markup in Code

One of the best free tutorials on defining a Swagger spec begins with this introduction also by Arnaud Lauret, the API Handyman.

There are on-line Swagger spec editors at:

If you fell you’re struggling with this. Let us help you.

Spec Gen

Swagger’s focus was originally serving Node.js developers, but additional langagues now make use of Swagger.

Generating Swagger specs from legacy code can be the most time consuming aspect.

  • Swashbuckle scans through C# WebAPI code and generates API website.

  • Doxygen is the de facto standard tool for generating documentation from annotated C source code. format comments in code can be picked up by the scanner.

  • Sandcastle

  • RDoc for Ruby code

  • JavaDocs generates code from comments in Java

Commentary about creating Swagger from code:

  • http://www.kobashicomputing.com/generating-documentation-from-c

Doxygen Gen

  1. Download the Doxygen UI.

Website Gen

Several tools generate API documentation in HTML for display on websites:

  • ReDoc
  • Microsoft Azure API Management, which charges.

  • Mashery’s IODocs is written to run on Node.js referencing a Redis key+value storage engine. See installation.

  • The Enunciate REST API framework is an open-source Java-based Web API framework. It creates full HTML documentation of the services it generates, where the documentation is assembled from JavaDocs comments.


Swagger Core stores JAX-RS API designs in JSON files from which Swagger UI dynamically generates beautiful HTML documentation.

Swagger makes use of Jackson, the multi-purpose Java library for processing JSON data format.

Swagger-core explains the use of maven build.

Sample endpoint


The standard Swagger spec doesn’t support some features. So vendor

  • Request body examples (mock server is generating them from Schema) https://help.apiary.io/tools/mock-server

  • Example values of HTTP headers

  • Multiple requests

Code Generators

https://www.manning.com/books/code-generation-in-action Manning published 2003 authored by Jack Herrington makes use of PHP to generate C, C++, C#, Java, Perl, SQL, and unit tests.

https://github.com/api-platform/api-platform API-first web framework on top of PHP Symfony with JSON-LD, Schema.org, and Hydra support https://api-platform.com



In her book Irresistible APIs Kirsten L. Hunter suggests these metrics:

  • Number of users reading or writing via the API
  • Usage through the API vs. through the main product
  • Number of applications interacting via the API
  • Number of new users coming through via third party applications

  • Ratio of read vs. write of new data
  • Percentage of unique content

“In order to communicate this with your customer developers, the information needs to be clearly available for them to read. The wording needs to be clear and approachable and make it easy for the developers to understand why you have the API and what you’re hoping to accomplish with your platform.”