April 2018
Intermediate to advanced
178 pages
3h 51m
English
Public APIs exposed on the web should be well documented, otherwise it would be difficult for developers to use them in their applications. While WADL definitions might be considered a source of documentation, they address a different problem—the discovery of the service. They serve metadata for the services to machines, not to humans. The Swagger project (https://swagger.io/) addresses the need for neat documentation of RESTful APIs. It defines a meta description of an API from an almost human-readable JSON format. The following is a sample swagger.json file, partially describing the catalog service:
{ "swagger": "2.0", "info": { "title": "Catalog API Documentation", "version": "v1" }, "paths": { "/categories/{id}" ...