Lead Image © smeagorl, 123RF.com
Swagger and OpenAPI Specification for documents
ElegantSpiceworks
Web applications often offer a REST interface for external use of their services. Developers address this from their own programs by accessing it through special URLs and HTTP requests, assuming the REST API is documented as completely as possible. A library that allows for a more convenient access to the service and thus facilitates the process of writing client programs would be even better.
However, for the web application vendor this involves much work: They not only need to develop the documentation and the library but also update both in case of any interface changes. A miracle tool named Swagger [1] automates both. Swagger is both a specification [2] and a collection of tools that generate interactive documentation for a REST API, and it's even a small software development kit (SDK) for client programs on request.
Division of Responsibilities
What initially sounds complicated proves to be remarkably simple in practice [3]. First, the developer describes the feature set of their REST API in a text file; it is written either manually or generated automatically from the source code of the web application. Generating it automatically implies that one of the frameworks supported by the Swagger tools is used, including JAX-RS [4] and Node.js [5]. In any case, two tools then access the API description and produce a complete API reference, as well as a matching SDK. The developer integrates the Swagger tools in the build process; the documentation and client SDK are automatically kept up to date.
Swagger, developed by SmartBear [6], comprises in part a
...
Buy this article as PDF
(incl. VAT)
Buy ADMIN Magazine
US / Canada
UK / Australia
Related content
-
Developing RESTful APIs
The popularity of REST APIs has increased of late, not only on industry sites, but also in the framework of smaller projects. We explain why this is so and illustrate the fairly abstract architectural approach with a concrete example. -
RESTful APIs in practice
Internet providers often market their open interfaces as RESTful, but is this true of the APIs, especially when no standard exists? We introduce some REST providers and look at how closely their API architectures reflect the REST principle. -
DevSecOps with DefectDojo
The DefectDojo vulnerability management tool helps development teams and admins identify, track, and fix vulnerabilities early in the software development process.
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Most Popular
Support Our Work
ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.
