It does your job. And helps others to do your job.
Overview
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:
-
<a target=”_blank” href=”https://help.apiary.io/tools/apiary-editor/> Apiary Editor</a>
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
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.
Dependencies
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
- petstore.swagger.io is provided for experimentation.
Format
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
Videos
-
Swagger make your REST APIs accessible Victor Trakhtenberg at DevconTLV October, 2013
-
Exposing Salesforce REST Services Using Swagger by Thys Michels (@thysmichels), Software Engineer at Lending Club describes REST app in Java Spring MVC annotations.
Metrics
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.”
Social
-
http://swagger.io/irc is provided (instead of a client), Swagger is on freenode.net in the #swagger channel.
-
Beautiful REST & JSON APIs video Aug. 7, 2013 by Les Hazelwood of StormPath | @Hazelwood