This is the Wordnik Swagger code for the express framework. For more on Swagger, please visit http://swagger.wordnik.com. For more on express, please visit https://github.com/visionmedia/express
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 express-based API
Include swagger.js in your app and add express as the app handler:
var express = url = swagger = ; var app = ;app; 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 express 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" ...
Mapping swagger to subpaths
To add a subpath to the api (i.e. list your REST api under /api
or /v1
), you can configure express as follows:
var app = ;var subpath = ; app;app; swagger;
Now swagger and all apis configured through it will live under the /v1
path (i.e. /v1/api-docs.json
).
Allows-origin and special headers
If you want to modify the default headers sent with every swagger-managed method, you can do so as follows:
swagger { res; res; res; res;};
If you have a special name for an api key (such as X-API-KEY
, per above), this is where you can inject it.