README
The swagger module provides tools for designing and building Swagger-compliant APIs entirely in Node.js. It integrates with popular Node.js servers, including Express, Hapi, Restify, and Sails, as well as any Connect-based middleware. With swagger, you can specify, build, and test your API from the very beginning, on your laptop. It allows you to change and iterate your design without rewriting the logic of your implementation.
Remember, one great thing about this approach is that all of the Swagger validation logic is handled for you, and all of the routing logic is managed through the Swagger configuration. You don't have to code (or recode!) any of that stuff yourself.
Your swagger API in five steps
1. Install the swagger module
Install using npm. For complete instructions, see the install page.
$ npm install -g dukeswag
2. Create a new swagger project
Use the CLI to create and manage projects. Learn more on the quick start page.
$ swagger project create hello-world
3. Design your API in the Swagger Editor
The interactive, browser-based Swagger Editor is built in. It provides Swagger 2.0 validation and endpoint routing, generates docs on the fly, and consumes easy-to-read YAML.
$ swagger project edit
4. Generate controllers for your API
The platform allows you to generate controllers automatically based on the Swagger Doc you put together. If you look at the Swagger file in the editor (shown in step 3 above), the x-swagger-router-controller element (line 17 in the editor screenshot) specifies the name of the controller file associated with the /hello path. For example:
paths:
/hello:
x-swagger-router-controller: hello_world
The operationId is an optional element specifies which controller function to call. Without it, the router looks for a function of the same name as the HTTP Method for the operation (ie "get","post"). In this case (line 19), it is a function called hello. If the operationId were omitted, the function would be get. Learn more.
Controller source code is always placed in ./api/controllers. So, the controller source file for this project is ./api/controllers/hello_world.js. To generate each of these controllers programmatically, run:
$ swagger project generate-routes
5. Write controller code in Node.js
The generator gives you easy entry points for your API. All you have to do is fill in the blanks. Code your API's business logic in Node.js.
excerpt from the generated example_controller.js controller
// Operation get
// Parameters expected:
// name(Optional)
controller["hello"] = function(req,res) {
//YOUR CODE GOES HERE
/*Example:
// variables defined in the Swagger document can be referenced using req.swagger.params.{parameter_name}
var name = req.swagger.params.name.value || 'stranger';
var hello = util.format('Hello, %s!', name);
// this sends back a JSON response which is a single string
res.json(hello);
*/
};
5. Test the server
Run the project server. Confirm that all your endpoints function as you expect. Running the server with the following command will run it without any of the security protections provided through the middleman server, and will use snakeoil ssl certificates. The way it's set up by default, your api will actually restart automatically as you make changes to its source so you can see them in realtime. Here is where you debug and build your endpoints!
$ swagger project start
6. Add SSL
Just drop your key and cert into the ssl folder of your server as cert.cert and key.key.
7. Run it for realz
The following command will run your server for real, with real ssl certs and HOTP request signing for the syndication server. The pm2 module is used to start it, and can be used to manage it as with any pm2 app. Now you're ready to offer your api and its secret key up to the syndication server, which will automatically take care of oauth, api keys, and rate limiting.
$ npm install -g pm2
$ pm2 start app.js
Installing the swagger module
See the Installing swagger for details.
Using the swagger module
Go to the swagger module doc page. It includes all the information you need to get started.
About this project
This initiative grew out of Apigee-127, an API design-first development framework using Swagger. Apigee donated the code to create the swagger-node project in 2015. All modifications have been contributed by Jason "Toolbox" Oettinger of Duke's Innovation Co-Lab
Copyright 2015 Apigee Corporation
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.