Free Resource: Documenting an Existing API with Swagger

  February 28, 2017

The Swagger framework helps define a language agnostic, human readable format for APIs, that eases implementation, drives adoption, and stabilizes development.

There are two general processes followed for generating a Swagger specification for an API:

  • Swagger Generation During Runtime: In this method, the Swagger contract is generated from an API based on the meta-data added against the various resources, methods and controllers. This meta-data will generate the Swagger contract, client-side code, and other artifacts during runtime. Typically, this meta-data would be in the form of code annotations. The tools trigger as the various methods and functions are called against their resources, and produces the Swagger contract from the metadata defined in the API.
  • Swagger Generation During Build Time: In this method, the Swagger contract is generated when preprocessing the API, that is, before runtime. Comments against various resources, methods and functions within the API help generate the Swagger specification. These comments are usually in a predefined, special syntax, based on the type of tool you use to generate the contract. The tool scans your API code for these special comments and produces the Swagger contract as an output

There are disadvantages and advantages offered by both methods. Generating the Swagger specification during runtime produces a more accurate API contract from the code, at the cost of software load in the form of additional dependencies, development time, and may add some overhead to the system. Conversely, generating the Swagger contract before runtime of the API is a more lightweight process, but there’s a good chance that the Swagger contract produced may not accurately describe your API, as it must be manually maintained.

The SwaggerHub Team recently published a free resource — Documenting an Existing API with Swagger looking at these two approaches to generating Swagger for your APIs.

You will learn:

  • The Importance of API Documentation
  • Why Use Swagger for Documentation
  • Approaches to Adding Swagger to Your APIs
  • Documenting Your Swagger Specification

Get your copy!