Swagger is a specification and a suite of tools to help you model and build a RESTful API.
- Xcode Command Line Tools
- Homebrew (the missing package manager for OSX)
Note: This post will walk you through the steps required to install the Xcode Command Line Tools, Homebrew and Node.js.
To install Swagger, enter the following command:
npm install -g swagger
Now, we can use the Swagger CLI to create the scaffolding for a new Microservices API project:
cd ~/opt/WebStorm/projects/ swagger project create qbuddy-api
Swagger will prompt you to choose a RESTful API framework, we're going to use Express.js so use the arrow key to select it. Swagger will create the scafolding for a new Express project and then run
npm install (for you) in order to install the required dependencies:
From the project directory we'll use the Swagger CLI to launch the newly scaffolded API, enter the following command:
swagger project start
Note: The server will restart if you make any changes to the project.
To test the API, run the following command in another Terminal session:
And, you'll get back the response 'Hello, World'.
The Swagger Editor
Swagger also includes an editor so that you can model your API interactively. From the project directory, enter the following command:
swagger project edit
npm install swagger-tools --save
Now, we just need to add a couple of lines to the project's
var SwaggerUi = require('swagger-tools/middleware/swagger-ui');
The project's updated
Now, when your server is running, this URL
http://localhost:10010/docs will serve the project's Swagger UI:
And, this URL
http://localhost:10010/api-docs will serve the Swagger document (
- Rob Ferguson's blog: Agile RESTful API Design