Hey Brad I keep hearing people talk about how we should use swagger to document our APIs but what the heck is that?

Good question, I too was confused by what exactly Swagger was because we talk about it as an API documentation tool similar to JSDocs but when you Google Swagger it appears to be so much more than that.

Swagger is not a code document generator like JSDocs or Doxygen but a framework for building APIs around the OpenAPI Specification.

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

The OpenAPI Specification is a meta language used to describe RESTful API in a way which is readable by both humans and machines. To me it sounds a lot like WSDL just that instead of XML OAS is JSON or YAML. When we talk about Swagger we are referring to a set of tools used to design, build, and document RESTful APIs using OAS.

With Swagger you can use the Editor tool to design your API by describing the API in OAS. With the CodeGen tool you can generate your service from the OAS description. With the Swagger UI tool, you can generate an interactive online documentation for your API based on the OAS description.

But I’ve already created my API in Node.js

Swagger is a set of developer tools you don’t have to use all the tools in the kit. You can just use Swagger to generate HTML based documentation of your API without using the editor or code generator.

To learn more about how to integrate Swagger into your existing Node.js service checkout Swaggerizing your API Documentation

Why use Swagger for Documentation?

Right if we’re only going to use one of the tools why bother using Swagger at all. Well Swagger does not just generate a static HTML document, it generates an interactive document which allows readers to actually call the API. They can test the different routes, posting or fetching data, without needing to setup any infrastructure. Think of it like documentation with Postman built in.

It’s the interactive nature of the documentation generated which makes Swagger for documentation a better option then a static HTML template.

Click here to learn more

There you have it that is what Swagger is, a developer tool kit for designing, building, and documenting RESTful APIs via the OpenAPI Specification.

I hope that was helpful, if you have any questions feel free to reach out I’m happy to help.

Until next time think imaginatively and design creatively