diff --git a/SAMPLE.md b/SAMPLE.md
deleted file mode 100644
index bc6b1f41..00000000
--- a/SAMPLE.md
+++ /dev/null
@@ -1,86 +0,0 @@
-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
-
-### To run the sample App
-
-You must first install dependencies:
-
-```js
-npm install
-```
-
-To run the sample server:
-```js
-node Apps/petstore/main.js
-```
-
-Then visit the server directly from your browser:
-
-```
-http://localhost:8002/api-docs
-```
-
-or from [swagger UI](https://github.com/wordnik/swagger-ui), mounted at `/docs`: [http://localhost:8002/docs](http://localhost:8002/docs).
-
-### How it works
-
-The swagger.js file is included when configuring the express server. There
-are a few additional steps to get the api to declare the swagger spec:
-
- main.js | |
|---|---|
Swagger Sample Application- -This is a sample application which uses the swagger-node-express -module. The application is organized in the following manner: - -petResources.js- -All API methods for this petstore implementation live in this file and are added to the swagger middleware. - -models.js- -This contains all model definitions which are sent & received from the API methods. - -petData.js- -This is the sample implementation which deals with data for this application | |
| Include express and swagger in the application. | var express = require("express")
- , url = require("url")
- , swagger = require("../../lib/swagger.js");
-
-var petResources = require("./petResources.js");
-
-var app = express();
-app.use(express.bodyParser()); |
| Set the main handler in swagger to the express app | swagger.setAppHandler(app); |
| This is a sample validator. It simply says that for all POST
-methods, the header | swagger.addValidator(
- function validate(req, path, httpMethod) { |
| example, only allow POST for api_key="special-key" | if ("POST" == httpMethod) {
- var apiKey = req.headers["api_key"];
- if (!apiKey) {
- apiKey = url.parse(req.url,true).query["api_key"]; }
- if ("special-key" == apiKey) {
- return true;
- }
- return false;
- }
- return true;
- }
-); |
| Add models and methods to swagger | swagger.addModels(petResources.models)
- .addGet(petResources.findByTags)
- .addGet(petResources.findByStatus)
- .addGet(petResources.findById)
- .addPost(petResources.addPet)
- .addPut(petResources.updatePet)
- .addDelete(petResources.deletePet); |
| Configures the app's base path and api version. | swagger.configure("http://localhost:8002", "0.1"); |
| Serve up swagger ui at /docs via static route | var docs_handler = express.static(__dirname + '/../../swagger-ui-1.1.1/');
-app.get(/^\/docs(\/.*)?$/, function(req, res, next) {
- if (req.url === '/docs') { // express static barfs on root url w/o trailing slash
- res.writeHead(302, { 'Location' : req.url + '/' });
- res.end();
- return;
- } |
| take off leading /docs so that connect locates file correctly | req.url = req.url.substr('/docs'.length);
- return docs_handler(req, res, next);
-}); |
| Start the server on port 8002 | app.listen(8002);
-
- |
paramTypes.js | |
|---|---|
| |
swagger.js | |
|---|---|
var resourcePath = "/resources.json";
-var basePath = "/";
-var swaggerVersion = "1.1";
-var apiVersion = "0.0";
-var resources = {};
-var validators = [];
-var appHandler = null;
-var allowedMethods = ['get', 'post', 'put', 'delete'];
-var allowedDataTypes = ['string', 'int', 'long', 'double', 'boolean', 'date', 'array'];
-var params = require(__dirname + '/paramTypes.js');
-var allModels = {}; | |
| Configuring swagger will set the basepath and api version for all -subdocuments. It should only be done once, and during bootstrap of the app | function configure(bp, av) {
- basePath = bp;
- apiVersion = av;
- setResourceListingPaths(appHandler);
- appHandler.get(resourcePath, resourceListing); |
| update resources if already configured | for(key in resources) {
- var r = resources[key];
- r.apiVersion = av;
- r.basePath = bp;
- }
-} |
| Convenience to set default headers in each response. | function setHeaders(res) {
- res.header('Access-Control-Allow-Origin', "*");
- res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
- res.header("Access-Control-Allow-Headers", "Content-Type, api_key");
- res.header("Content-Type", "application/json; charset=utf-8");
-} |
| creates declarations for each resource path. | function setResourceListingPaths(app) {
- for (var key in resources) {
- app.get("/" + key.replace("\.\{format\}", ".json"), function(req, res) {
- var r = resources[req.url.substr(1).split('?')[0].replace('.json', '.{format}')];
- if (!r)
- return stopWithError(res, {'description': 'internal error', 'code': 500});
- else {
- setHeaders(res);
- var key = req.url.substr(1).replace('.json', '.{format}').split('?')[0];
- var data = filterApiListing(req, res, resources[key]);
- data.basePath = basePath;
- if (data.code) {
- res.send(data, data.code); }
- else {
- res.send(JSON.stringify(filterApiListing(req, res, r)));
- }
- }
- });
- }
-} |
| Applies a filter to an api listing. When done, the api listing will only contain -methods and models that the user actually has access to. | function filterApiListing(req, res, r) {
- var route = req.route;
- var excludedPaths = [];
-
- if (!r || !r.apis) {
- return stopWithError(res, {'description': 'internal error', 'code': 500});
- }
-
- for (var key in r.apis) {
- var api = r.apis[key];
- for (var opKey in api.operations) {
- var op = api.operations[opKey];
- var path = api.path.replace(/{.*\}/, "*");
- if (!canAccessResource(req, route + path, op.httpMethod)) {
- excludedPaths.push(op.httpMethod + ":" + api.path); }
- }
- } |
| clone attributes in the resource | var output = shallowClone(r);
- |
| models required in the api listing | var requiredModels = [];
- |
| clone methods that user can access | output.apis = [];
- var apis = JSON.parse(JSON.stringify(r.apis));
- for (var i in apis) {
- var api = apis[i];
- var clonedApi = shallowClone(api);
-
- clonedApi.operations = [];
- var shouldAdd = true;
- for (var o in api.operations) {
- var operation = api.operations[o];
- if (excludedPaths.indexOf(operation.httpMethod + ":" + api.path) >= 0) {
- break;
- }
- else {
- clonedApi.operations.push(JSON.parse(JSON.stringify(operation)));
- addModelsFromResponse(operation, requiredModels);
- }
- } |
| only add cloned api if there are operations | if (clonedApi.operations.length > 0) {
- output.apis.push(clonedApi);
- }
- } |
| add required models to output | output.models = {};
- for (var i in requiredModels){
- var modelName = requiredModels[i];
- var model = allModels.models[modelName];
- if(model){
- output.models[requiredModels[i]] = model;
- }
- } |
| look in object graph | for (key in output.models) {
- var model = output.models[key];
- if (model && model.properties) {
- for (var key in model.properties) {
- var t = model.properties[key].type;
-
- switch (t){
- case "Array":
- if (model.properties[key].items) {
- var ref = model.properties[key].items.$ref;
- if (ref && requiredModels.indexOf(ref) < 0) {
- requiredModels.push(ref);
- }
- }
- break;
- case "string":
- case "long":
- break;
- default:
- if (requiredModels.indexOf(t) < 0) {
- requiredModels.push(t);
- }
- break;
- }
- }
- }
- }
- for (var i in requiredModels){
- var modelName = requiredModels[i];
- if(!output[modelName]) {
- var model = allModels.models[modelName];
- if(model){
- output.models[requiredModels[i]] = model;
- }
- }
- }
- return output;
-} |
| Add model to list and parse List[model] elements | function addModelsFromResponse(operation, models){
- var responseModel = operation.responseClass;
- if (responseModel) {
- responseModel = responseModel.replace(/^List\[/,"").replace(/\]/,"");
- if (models.indexOf(responseModel) < 0) {
- models.push(responseModel);
- }
- }
-} |
| clone anything but objects to avoid shared references | function shallowClone(obj) {
- var cloned = {};
- for (var i in obj) {
- if (typeof (obj[i]) != "object") {
- cloned[i] = obj[i];
- }
- }
- return cloned;
-} |
| function for filtering a resource. override this with your own implementation. -if consumer can access the resource, method returns true. | function canAccessResource(req, path, httpMethod) {
- for (var i in validators) {
- if (!validators[i](req,path,httpMethod))
- return false;
- }
- return true;
-}
-
-/**
- * returns the json representation of a resource
- *
- * @param request
- * @param response
- */
-function resourceListing(req, res) {
- var r = {
- "apiVersion" : apiVersion,
- "swaggerVersion" : swaggerVersion,
- "basePath" : basePath,
- "apis" : []
- };
-
- for (var key in resources)
- r.apis.push({"path": "/" + key, "description": "none"});
-
- setHeaders(res);
- res.write(JSON.stringify(r));
- res.end();
-} |
| Adds a method to the api along with a spec. If the spec fails to validate, it won't be added | function addMethod(app, callback, spec) {
- var rootPath = spec.path.split("/")[1];
- var root = resources[rootPath];
-
- if (root && root.apis) {
- for (var key in root.apis) {
- var api = root.apis[key];
- if (api && api.path == spec.path && api.method == spec.method) { |
| Add & return | appendToApi(root, api, spec);
- return;
- }
- }
- }
-
- var api = {"path" : spec.path};
- if (!resources[rootPath]) {
- if (!root) {
- var resourcePath = "/" + rootPath.replace("\.\{format\}", "");
- root = {
- "apiVersion" : apiVersion, "swaggerVersion": swaggerVersion, "basePath": basePath, "resourcePath": resourcePath, "apis": [], "models" : []
- };
- }
- resources[rootPath] = root;
- }
-
- root.apis.push(api);
- appendToApi(root, api, spec); |
| TODO: only supports json - convert .{format} to .json, make path params happy | var fullPath = spec.path.replace("\.\{format\}", ".json").replace(/\/{/g, "/:").replace(/\}/g,"");
- var currentMethod = spec.method.toLowerCase();
- if (allowedMethods.indexOf(currentMethod)>-1) {
- app[currentMethod](fullPath, function(req,res) {
- setHeaders(res);
- if (!canAccessResource(req, req.url.substr(1).split('?')[0].replace('.json', '.*'), req.method)) {
- res.send(JSON.stringify({"description":"forbidden", "code":403}), 403);
- } else {
- try {
- callback(req,res);
- }
- catch (ex) {
- if (ex.code && ex.description)
- res.send(JSON.stringify(ex), ex.code);
- else {
- console.error(spec.method + " failed for path '" + require('url').parse(req.url).href + "': " + ex);
- res.send(JSON.stringify({"description":"unknown error","code":500}), 500);
- }
- }
- }
- });
- } else {
- console.log('unable to add ' + currentMethod.toUpperCase() + ' handler');
- return;
- }
-} |
| Set expressjs app handler | function setAppHandler(app) {
- appHandler = app;
-} |
| Add swagger handlers to express | function addHandlers(type, handlers) {
- for (var i = 0; i < handlers.length; i++) {
- var handler = handlers[i];
- handler.spec.method = type;
- addMethod(appHandler, handler.action, handler.spec);
- }
-} |
| Discover swagger handler from resource | function discover(resource) {
- for (var key in resource) {
- if (resource[key].spec && resource[key].spec.method && allowedMethods.indexOf(resource[key].spec.method.toLowerCase())>-1) {
- addMethod(appHandler, resource[key].action, resource[key].spec);
- }
- else
- console.log('auto discover failed for: ' + key);
- }
-} |
| Discover swagger handler from resource file path | function discoverFile(file) {
- return discover(require(file));
-} |
| adds get handler | function addGet() {
- addHandlers('GET', arguments);
- return this;
-} |
| adds post handler | function addPost() {
- addHandlers('POST', arguments);
- return this;
-} |
| adds delete handler | function addDelete() {
- addHandlers('DELETE', arguments);
- return this;
-} |
| adds put handler | function addPut() {
- addHandlers('PUT', arguments);
- return this;
-} |
| adds models to swagger | function addModels(models) {
- allModels = models;
- return this;
-}
-
-function wrap(callback, req, resp){
- callback(req,resp);
-}
-
-function appendToApi(rootResource, api, spec) {
- if (!api.description) {
- api.description = spec.description;
- }
- var validationErrors = [];
-
- if(!spec.nickname || spec.nickname.indexOf(" ")>=0){ |
| nicknames don't allow spaces | validationErrors.push({"path": api.path, "error": "invalid nickname '" + spec.nickname + "'"});
- } |
| validate params | for ( var paramKey in spec.params) {
- var param = spec.params[paramKey];
- if(param.allowableValues) {
- var avs = param.allowableValues.toString();
- var type = avs.split('[')[0];
- if(type == 'LIST'){
- var values = avs.match(/\[(.*)\]/g).toString().replace('\[','').replace('\]', '').split(',');
- param.allowableValues = {valueType: type, values: values};
- }
- else if (type == 'RANGE') {
- var values = avs.match(/\[(.*)\]/g).toString().replace('\[','').replace('\]', '').split(',');
- param.allowableValues = {valueType: type, min: values[0], max: values[1]};
- }
- }
-
- switch (param.paramType) {
- case "path":
- if (api.path.indexOf("{" + param.name + "}") < 0) {
- validationErrors.push({"path": api.path, "name": param.name, "error": "invalid path"});
- }
- break;
- case "query":
- break;
- case "body":
- break;
- default:
- validationErrors.push({"path": api.path, "name": param.name, "error": "invalid param type " + param.paramType});
- break;
- }
- }
-
- if (validationErrors.length > 0) {
- console.log(validationErrors);
- return;
- }
-
- if (!api.operations) {
- api.operations = []; } |
| TODO: replace if existing HTTP operation in same api path | var op = {
- "parameters" : spec.params,
- "httpMethod" : spec.method,
- "notes" : spec.notes,
- "errorResponses" : spec.errorResponses,
- "nickname" : spec.nickname,
- "summary" : spec.summary
- };
-
- if (spec.responseClass) {
- op.responseClass = spec.responseClass;
- }
- else {
- op.responseClass = "void";
- }
- api.operations.push(op);
-
- if (!rootResource.models) {
- rootResource.models = {};
- }
-}
-
-function addValidator(v) {
- validators.push(v);
-} |
| Create Error JSON by code and text | function error(code, description) {
- return {"code" : code, "description" : description};
-} |
| Stop express ressource with error code | function stopWithError(res, error) {
- setHeaders(res);
- if (error && error.description && error.code)
- res.send(JSON.stringify(error), error.code);
- else
- res.send(JSON.stringify({'description': 'internal error', 'code': 500}), 500);
-} |
| Export most needed error types for easier handling | exports.errors = {
- 'notFound': function(field, res) {
- if (!res) {
- return {"code": 404, "description": field + ' not found'}; }
- else {
- res.send({"code": 404, "description": field + ' not found'}, 404); }
- },
- 'invalid': function(field, res) {
- if (!res) {
- return {"code": 400, "description": 'invalid ' + field}; }
- else {
- res.send({"code": 400, "description": 'invalid ' + field}, 404); }
- },
- 'forbidden': function(res) {
- if (!res) {
- return {"code": 403, "description": 'forbidden' }; }
- else {
- res.send({"code": 403, "description": 'forbidden'}, 403); }
- }
-};
-
-exports.params = params;
-exports.queryParam = exports.params.query;
-exports.pathParam = exports.params.path;
-exports.postParam = exports.params.post;
-exports.getModels = allModels;
-
-exports.error = error;
-exports.stopWithError = stopWithError;
-exports.stop = stopWithError;
-exports.addValidator = addValidator;
-exports.configure = configure;
-exports.canAccessResource = canAccessResource;
-exports.resourcePath = resourcePath;
-exports.resourceListing = resourceListing;
-exports.setHeaders = setHeaders;
-exports.addGet = addGet;
-exports.addPost = addPost;
-exports.addPut = addPut;
-exports.addDelete = addDelete;
-exports.addGET = addGet;
-exports.addPOST = addPost;
-exports.addPUT = addPut;
-exports.addDELETE = addDelete;
-exports.addModels = addModels;
-exports.setAppHandler = setAppHandler;
-exports.discover = discover;
-exports.discoverFile = discoverFile;
-
- |