Add notes on relative paths

Surnet · Sep 16, 2018 · a9d9bc6 · a9d9bc6
1 parent 6177568
commit a9d9bc6
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 48 deletions.
diff --git a/docs/CLI.md b/docs/CLI.md
@@ -19,7 +19,7 @@ Swagger-jsdoc will read the `apis` array in your definition file by default for
 $ swagger-jsdoc -d swaggerDef.js -o doc.json
 ```
 
-This could be any .js, .json, .yml or .yaml file.
+This could be any `.js`, `.json`, `.yml` or `.yaml` file.
 
 #### Specify input files (optional)
 
@@ -29,6 +29,8 @@ $ swagger-jsdoc route1.js route2.js
 
 Free form input, can be before or after definition. [Glob patterns](https://github.com/isaacs/node-glob) are acceptable to match multiple files with same extension `*.js`, `*.php`, etc. or patterns selecting files in nested folders as `**/*.js`, `**/*.php`, etc.
 
+These paths are relative to current directory from which `swagger-jsdoc` is ran, not the application holding the APIs.
+
 #### Specify output file (optional)
 
 ```

diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md
@@ -12,9 +12,12 @@ const options = {
       version: '1.0.0', // Version (required)
     },
   },
-  apis: ['./routes.js'], // Path to the API docs
+  // Path to the API docs
+  apis: ['./routes.js'],
 };
 
+Please note that relative paths in `apis` are relative to the current directory from which the Node.js program is ran, not the application serving the APIs.
+
 // Initialize swagger-jsdoc -> returns validated swagger spec in json format
 const swaggerSpec = swaggerJSDoc(options);
 ```
@@ -102,56 +105,59 @@ model and add fields.
  */
 
 /**
-   * @swagger
-   * /users:
-   *   get:
-   *     description: Returns users
-   *     produces:
-   *      - application/json
-   *     responses:
-   *       200:
-   *         description: users
-   *         schema:
-   *           type: array
-   *           items:
-   *             $ref: '#/definitions/User'
-   */
-  app.get('/users', function(req, res) {
-    res.json([ {
+ * @swagger
+ * /users:
+ *   get:
+ *     description: Returns users
+ *     produces:
+ *      - application/json
+ *     responses:
+ *       200:
+ *         description: users
+ *         schema:
+ *           type: array
+ *           items:
+ *             $ref: '#/definitions/User'
+ */
+app.get('/users', function(req, res) {
+  res.json([
+    {
       id: 1,
       username: 'jsmith',
-    }, {1
+    },
+    {
       id: 2,
       username: 'jdoe',
-    } ]);
-  });
-
-  /**
-   * @swagger
-   * /users:
-   *   post:
-   *     description: Creates a user
-   *     produces:
-   *       - application/json
-   *     parameters:
-   *       - name: user
-   *         description: User object
-   *         in:  body
-   *         required: true
-   *         type: string
-   *         schema:
-   *           $ref: '#/definitions/NewUser'
-   *     responses:
-   *       200:
-   *         description: users
-   *         schema:
-   *           $ref: '#/definitions/User'
-   */
-  app.post('/users', function(req, res) {
-    // Generate ID
-    req.body.id = Math.floor(Math.random() * 100) * 1
-    res.json(req.body);
-  });
+    },
+  ]);
+});
+
+/**
+ * @swagger
+ * /users:
+ *   post:
+ *     description: Creates a user
+ *     produces:
+ *       - application/json
+ *     parameters:
+ *       - name: user
+ *         description: User object
+ *         in:  body
+ *         required: true
+ *         type: string
+ *         schema:
+ *           $ref: '#/definitions/NewUser'
+ *     responses:
+ *       200:
+ *         description: users
+ *         schema:
+ *           $ref: '#/definitions/User'
+ */
+app.post('/users', function(req, res) {
+  // Generate ID
+  req.body.id = Math.floor(Math.random() * 100) * 1;
+  res.json(req.body);
+});
 ```
 
 Keep in mind that since v3 of the specification, you can use [components](https://swagger.io/docs/specification/components/) in order to definite and reuse resources.

diff --git a/example/v2/app.js b/example/v2/app.js
@@ -38,6 +38,7 @@ const options = {
   // Import swaggerDefinitions
   swaggerDefinition,
   // Path to the API docs
+  // Note that this path is relative to the current directory from which the Node.js is ran, not the application itself.
   apis: ['./example/v2/routes*.js', './example/v2/parameters.yaml'],
 };