Merge pull request #3 from chdanielmueller/master

Prepare for version 1.0

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

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

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);
+  });
 };

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
  */

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;
 };

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",

test/swagger-spec.json

@@ -10,7 +10,7 @@
   "paths": {
     "/": {
       "get": {
-        "description": "Returns Hello World!",
+        "description": "Returns the homepage",
         "responses": {
           "200": {
             "description": "hello world"