This is the Wordnik Swagger code for the restify framework. It's a fork of https://github.com/wordnik/swagger-node-express.git with some fixes to work with Restify.
For more on Swagger, please visit http://swagger.wordnik.com.
For more on restify, please visit http://mcavage.me/node-restify
READ MORE about swagger!
See the swagger website or the swagger-core wiki, which contains information about the swagger json spec.
Try a sample! The source for a functional sample is available on github:
Adding swagger to your restify-based API
Include swagger.js in your app and add restify as the app handler:
var restify = url = swagger = ; var server = restify;server;restify { this;}; swagger;
You can optionally add a validator function, which is used to filter the swagger json and request operations:
// This is a sample validator. It simply says that for _all_ POST, DELETE, PUT methods, // the header api_key OR query param api_key must be equal to the string literal // special-key. All other HTTP ops are A-OK */ swagger;
You now add models to the swagger context. Models are described in a JSON format, per the swagger model specification. Most folks keep them in a separate file (see here for an example), or you can add them as such:
swagger;
Next, add some resources. Each resource contains a swagger spec as well as the action to execute when called. The spec contains enough to describe the method, and adding the resource will do the rest. For example:
var findById = 'spec': "description" : "Operations about pets" "path" : "/pet.{format}/{petId}" "notes" : "Returns a pet based on ID" "summary" : "Find pet by ID" "method": "GET" "params" : swagger "responseClass" : "Pet" "errorResponses" : swaggererrors swaggererrors "nickname" : "getPetById" { if !reqparamspetId throw swaggererrors; var id = ; var pet = petData; ifpet res; else throw swaggererrors; }; swagger;
Adds an API route to restify and provides all the necessary information to swagger.
Finally, configure swagger with a public
URL and version:
swagger;
and the server can be started:
app;
Now you can open up a swagger-ui and browse your API, generate a client with swagger-codegen, and be happy.
Other Configurations
.{format} suffix removal
If you don't like the .{format} or .json suffix, you can override this before configuring swagger:
swagger;
That will put the resource listing under /api-docs
, and ditch the .{format}
on each of the apis you're adding to. Make sure to set the paths correctly in your spec configuration though, like such:
// note the .{format} is removed from the path!var findById = 'spec': "description" : "Operations about pets" "path" : "/pet/{petId}" "notes" : "Returns a pet based on ID" ...