Building Node.js APIs with Swagger
Last summer we started building open-source tools to make developing and deploying APIs using Node.js easier and more enjoyable. Early in the design phase, we realized that we wanted to integrate Swagger so that all APIs created and exposed as part of our tooling would ship with nice documentation. As we began working on Apigee-127 we quickly realized that Swagger should be more than something we integrated—it should become an integral part of our product.
In this post, we’ll introduce swagger-tools, an open source project that plays a big role in Apigee-127 and provides tools for building APIs with Node.js and Swagger. But before we talk about swagger-tools, let’s quickly discuss Swagger and what led up to the development of swagger-tools.
Swagger is a documentation format for REST APIs. Using Swagger, you can describe the available endpoints your API exposes, the contract/interface consuming those API endpoints, and more. In addition to providing a common format for describing REST APIs, there’s also a nice user interface for Swagger called swagger-ui that creates documentation for your REST API and even gives you a built-in client for interacting with your REST API. The Swagger community also provides a number of libraries and tools for integrating Swagger into your project.
Everything was going great with Swagger and Apigee-127 until we realized that there was no tooling for validating Swagger documents. Swagger ships with JSON Schema files that enable the use of a JSON schema validator to ensure that Swagger documents are structurally sound. This is a great start, but if you read the Swagger specification you'll see that there are things missing from JSON schema files that need to be validated as well. Because of this, we created swagger-tools.
Swagger-tools started life as an API to fully validate Swagger documents. Now, it’s much more than that. In fact, swagger-tools plays a key role behind the features found in Apigee-127. To give you a better idea of what swagger-tools is, let's look at the things that swagger-tools provides, including:
a command-line tool
Connect-compatible middleware (which enables the core features of Apigee-127)
Swagger-tools provides a few APIs for interacting with Swagger documents and it also provides metadata for the Swagger specification, including the location of documentation or schema files for a specific version of Swagger. Most of the APIs right now are centered around the problem we initially set out to solve: validation.
Here’s a quick list of the available APIs swagger-tools provides:
composeModel - this function creates a JSON schema file for a model by name or reference
convert - this function converts your Swagger 1.2 document to a Swagger 2.0 document
resolve - this function takes your Swagger document(s) and returns a fully resolved document (all external and internal references are replaced with their resolved values)
validate - this function validates your Swagger document(s)
validateModel - this function validates your model value against its schema in your Swagger document(s)
Swagger-tools also provides a CLI for performing some of the APIs against your Swagger document(s). Below is a list of commands you can run with the swagger-tools CLI:
convert <resourceListing> [apiDeclarations...] - converts the Swagger 1.2 documents to a Swagger 2.0 document
info <version> - prints out Swagger specification information for the provided version
validate <resourceListingOrSwaggerObject> [apiDeclarations...] - validates the Swagger document(s)
All of these CLI commands can be run against local files and remote files, and the files can be JSON or YAML. For more details on the CLI commands and their usage, please view the project documentation here: https://github.com/apigee-127/swagger-tools/blob/master/docs/CLI.md
While the API and CLI are really useful, the swagger-tools’ Connect middleware is where things get really interesting when it comes to building APIs with Swagger. Swagger-tools ships with Connect middleware that enables you to describe your API contract in one place and have your Node.js request/response lifecycle use the information in your Swagger document(s) to do things like validate requests, validate responses, mock responses, and request routing. To get a better idea of what is available, here’s the current middleware shipped with swagger-tools:
swaggerMetadata - this attaches pertinent Swagger information to your req object if/when the request matches an API described in your Swagger document(s) (this middleware is required by all other middlewares, except where noted)
swaggerRouter - this gives you a simple way to do request routing so that whenever a Swagger route is requested, the appropriate code is executed
swaggerSecurity - this enables you to do pre-route security checks based on information in your Swagger document(s)
swaggerUi - this deploys swagger-ui alongside your API for easy access to your API’s documentation (this middleware does not require swaggerMetadata)
swaggerValidator - this performs request validation, and optional response validation, based on the contract defined in your Swagger document(s)
For more information on this middleware and how to wire them up in your server environment, please view the project documentation here: https://github.com/apigee-127/swagger-tools/blob/master/docs/Middleware.md
Swagger-tools enables you to easily develop REST APIs using Node.js. To avoid rewriting a lot of documentation already provided by the swagger-tools project, we suggest that if you want to know more specifics on how to use swagger-tools, read the swagger-tools documentation. This documentation will tell you how to install swagger-tools, how to use the API, how to use the CLI, and even how to use the middleware so that your API has one source of truth: the Swagger document(s).
Hopefully you have a clearer understanding of what swagger-tools brings to the table. If you’d like to see an end-to-end example of building a Node.js API with swagger-tools, check out the Quick Start guide in the swagger-tools documentation. Because swagger-tools is open source, please feel free to get involved. Pull requests are encouraged, as is filing bug/enhancement requests and any other feedback.