diff --git a/README.md b/README.md index 2b45ca86..bb73faea 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,53 @@ ## Install +```bash +$ npm install swagger-jsdoc --save +``` ## Quick Start +swagger-jsdoc returns the validated swagger specification as JSON. + +```javascript +var swaggerJSDoc = require('swagger-jsdoc'); + +var options = { + swaggerDefinition: { + info: { + title: 'Hello World', // Title (required) + version: '1.0.0', // Version (required) + }, + }, + apis: ['./routes.js'], // Path to the API docs +}; + +// Initialize swagger-jsdoc -> returns validated swagger spec in json format +var swaggerSpec = swaggerJSDoc(options); +``` + +At this time you can do with the swaggerSpec whatever you want. +The simplest way would be serving it straight to the outside world: + +```javascript +app.get('/api-docs.json', function(req, res) { + res.setHeader('Content-Type', 'application/json'); + res.send(swaggerSpec); +}); +``` + +You could also use a framework like [swagger-tools](https://www.npmjs.com/package/swagger-tools) to serve the spec and a swagger-ui. ## Example App +There is an example app in the example subdirectory. +To use it you can use the following commands: + +```bash +$ git clone https://github.com/Surnet/swagger-jsdoc.git +$ cd swagger-jsdoc +$ npm install +$ npm start +``` + +The swagger spec will be served at http://localhost:3000/api-docs.json \ No newline at end of file diff --git a/example/app.js b/example/app.js index 51bedfac..9331cd5a 100644 --- a/example/app.js +++ b/example/app.js @@ -5,7 +5,7 @@ var express = require('express'); var bodyParser = require('body-parser'); var routes = require('./routes'); -var swagger = require('../'); +var swaggerJSDoc = require('../'); // Initialize express @@ -32,15 +32,20 @@ var swaggerDefinition = { // Options for the swagger docs var options = { - apiDocs: '/api-docs.json', // Default: '/api-docs', optional - swaggerUi: '/docs', // Path to the swaggerUI (default: '/docs', optional) swaggerDefinition: swaggerDefinition, // Import swaggerDefinitions apis: ['./example/routes.js'], // Path to the API docs }; -// Initialize swagger-jsdoc -swagger.init(app, options); +// Initialize swagger-jsdoc -> returns validated swagger spec in json format +var swaggerSpec = swaggerJSDoc(options); + + +// Serve swagger docs the way you like (Recommendation: swagger-tools) +app.get('/api-docs.json', function(req, res) { + res.setHeader('Content-Type', 'application/json'); + res.send(swaggerSpec); +}); // Set up the routes diff --git a/example/routes.js b/example/routes.js index 6ae53638..53c74ae1 100644 --- a/example/routes.js +++ b/example/routes.js @@ -1,55 +1,47 @@ 'use strict'; -// Handler for the Homepage -function rootHandler(req, res) { - res.send('Hello World!'); -} - - -// Handler for Login -function loginHandler(req, res) { - res.json(req.body); -} - - // Sets up the routes. module.exports.setup = function(app) { /** - * @swagger - * /: - * get: - * description: Returns Hello World! - * responses: - * 200: - * description: hello world + * @swagger + * /: + * get: + * description: Returns the homepage + * responses: + * 200: + * description: hello world */ - app.get('/', rootHandler); + app.get('/', function(req, res) { + res.send('Hello World!'); + }); /** - * @swagger - * /login: - * post: - * description: Login to the application - * produces: - * - application/json - * parameters: - * - name: username - * description: Username to use for login. - * in: formData - * required: true - * type: string - * - name: password - * description: User's password. - * in: formData - * required: true - * type: string - * responses: - * 200: - * description: login + * @swagger + * /login: + * post: + * description: Login to the application + * produces: + * - application/json + * parameters: + * - name: username + * description: Username to use for login. + * in: formData + * required: true + * type: string + * - name: password + * description: User's password. + * in: formData + * required: true + * type: string + * responses: + * 200: + * description: login */ - app.post('/login', loginHandler); + app.post('/login', function(req, res) { + res.json(req.body); + }); }; \ No newline at end of file diff --git a/external.jsdoc b/external.jsdoc index 9618f1ca..f8a5d5e8 100644 --- a/external.jsdoc +++ b/external.jsdoc @@ -15,9 +15,9 @@ */ /** - * Various tools for using and integrating with Swagger. - * @external module:swagger-tools + * Swagger JSON/YAML parser and validator for Node and browsers + * @external module:swagger-parser * @global - * @see https://www.npmjs.com/package/swagger-tools + * @see https://www.npmjs.com/package/swagger-parser * @license MIT */ \ No newline at end of file diff --git a/lib/index.js b/lib/index.js index 8c1e9936..e7f0606b 100644 --- a/lib/index.js +++ b/lib/index.js @@ -7,7 +7,7 @@ var fs = require('fs'); var path = require('path'); var doctrine = require('doctrine'); var jsYaml = require('js-yaml'); -var swaggerTools = require('swagger-tools'); +var parser = require('swagger-parser'); /** @@ -84,18 +84,14 @@ function addDataToSwaggerObject(swaggerObject, swaggerJsDocComments) { } -// This is the Swagger object that conforms to the Swagger 2.0 specification. -module.exports.swaggerObject = []; - - /** - * Initializes the module. This is intended to be called only once. + * Generates the swagger spec * @function - * @param {object} app - Express application * @param {object} options - Configuration options - * @requires swagger-tools + * @returns {array} Swagger spec + * @requires swagger-parser */ -module.exports.init = function(app, options) { +module.exports = function(options) { /* istanbul ignore if */ if (!options) { throw new Error('\'options\' is required.'); @@ -106,37 +102,23 @@ module.exports.init = function(app, options) { } // Build basic swagger json - module.exports.swaggerObject = options.swaggerDefinition; - module.exports.swaggerObject.swagger = '2.0'; - module.exports.swaggerObject.paths = {}; + var swaggerObject = []; + swaggerObject = options.swaggerDefinition; + swaggerObject.swagger = '2.0'; + swaggerObject.paths = {}; // Parse the documentation in the APIs array. for (var i = 0; i < options.apis.length; i = i + 1) { var jsDocComments = parseApiFile(options.apis[i]); var swaggerJsDocComments = filterJsDocComments(jsDocComments); - addDataToSwaggerObject(module.exports.swaggerObject, swaggerJsDocComments); + addDataToSwaggerObject(swaggerObject, swaggerJsDocComments); } - var swaggerToolsUIOptions = { - apiDocs: options.apiDocs, - swaggerUi: options.swaggerUi, - }; - - // Initialize the Swagger middleware - swaggerTools.initializeMiddleware(module.exports.swaggerObject, - function(middleware) { - // Interpret Swagger resources and attach metadata to request - // must be first in swagger-tools middleware chain - app.use(middleware.swaggerMetadata()); - - // Validate Swagger requests - app.use(middleware.swaggerValidator()); - - // Route validated requests to appropriate controller - app.use(middleware.swaggerRouter()); - - // Serve the Swagger documents and Swagger UI - app.use(middleware.swaggerUi(swaggerToolsUIOptions)); + parser.parse(swaggerObject, function(err, api) { + if (!err) { + swaggerObject = api; } - ); + }); + + return swaggerObject; }; diff --git a/package.json b/package.json index 2aa4dcf2..e5cbfa75 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "swagger-jsdoc", - "version": "0.0.0", + "version": "1.0.0", "description": "Generates swagger doc based on JSDoc", "main": "index.js", "scripts": { @@ -29,7 +29,7 @@ "dependencies": { "doctrine": "^0.6.4", "js-yaml": "^3.3.1", - "swagger-tools": "^0.8.7" + "swagger-parser": "^2.4.2" }, "devDependencies": { "body-parser": "^1.12.4", diff --git a/test/swagger-spec.json b/test/swagger-spec.json index 168f6160..a5da81f6 100644 --- a/test/swagger-spec.json +++ b/test/swagger-spec.json @@ -10,7 +10,7 @@ "paths": { "/": { "get": { - "description": "Returns Hello World!", + "description": "Returns the homepage", "responses": { "200": { "description": "hello world"