Fix bug with relative/YAML references

Fixes #17

README.md

@@ -33,8 +33,8 @@ bower install sway --save
 
 The standalone binaries come in two flavors:
 
-* [sway-standalone.js](https://raw.github.com/apigee-127/sway/master/browser/sway.js): _3,980kb_, full source  and source maps
-* [sway-standalone-min.js](https://raw.github.com/apigee-127/sway/master/browser/sway-min.js): _584kb_, minified, compressed and no source map
+* [sway-standalone.js](https://raw.github.com/apigee-127/sway/master/browser/sway.js): _3,996kb_, full source  and source maps
+* [sway-standalone-min.js](https://raw.github.com/apigee-127/sway/master/browser/sway-min.js): _588kb_, minified, compressed and no source map
 
 **Note:** I realize these browser binaries are not small.  For the most part, this is due to a library we are using for
 creating mock/sample parameters/responses.  [json-schema-faker](https://github.com/pateketrueke/json-schema-faker) uses

RELEASE_NOTES.md

@@ -1,7 +1,9 @@
 ## Release Notes
 
-### TBD
+### v0.2.1
 
+* Fix bug with loading relative references *(Issue #17)*
+* Fix bug with loading YAML references *(Issue #17)*
 * Make errors in `SwaggerApi#create` handleable *(Issue #16)*
 
 ### v0.2.0 (2015-08-25)

docs/README.md

@@ -28,8 +28,8 @@ bower install sway --save
 
 The standalone binaries come in two flavors:
 
-* [sway-standalone.js](https://raw.github.com/apigee-127/sway/master/browser/sway.js): _3,980kb_, full source  and source maps
-* [sway-standalone-min.js](https://raw.github.com/apigee-127/sway/master/browser/sway-min.js): _584kb_, minified, compressed and no source map
+* [sway-standalone.js](https://raw.github.com/apigee-127/sway/master/browser/sway.js): _3,996kb_, full source  and source maps
+* [sway-standalone-min.js](https://raw.github.com/apigee-127/sway/master/browser/sway-min.js): _588kb_, minified, compressed and no source map
 
 **Note:** I realize these browser binaries are not small.  For the most part, this is due to a library we are using for
 creating mock/sample parameters/responses.  [json-schema-faker](https://github.com/pateketrueke/json-schema-faker) uses

lib/versions/2.0/index.js

@@ -28,10 +28,12 @@ var _ = require('lodash');
 var JsonRefs = require('json-refs');
 var formatGenerators = require('./format-generators');
 var helpers = require('../../helpers');
+var path = require('path');
 var pathToRegexp = require('path-to-regexp');
 var types = require('../../types');
 var validators = require('./validators');
 var vHelpers = require('./helpers');
+var YAML = require('js-yaml');
 
 var docsUrl = 'https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md';
 var mocker = helpers.createJSONSchemaMocker({
@@ -68,8 +70,22 @@ module.exports.canProcess = function (definition) {
  * @returns {Promise} A promise that resolves the SwaggerApi after processing
  */
 module.exports.createSwaggerApi = function (definition, options) {
+  var jsonRefsOptions = options.jsonRefs || {};
+
+  // Update the json-refs options to use the definition location
+  if (_.isString(options.definition)) {
+    jsonRefsOptions.location = path.dirname(options.definition);
+  }
+
+  // Update the json-refs options to process YAML
+  if (_.isUndefined(jsonRefsOptions.processContent)) {
+    jsonRefsOptions.processContent = function (content) {
+      return YAML.safeLoad(content);
+    }
+  }
+
   return new Promise(function (resolve, reject) {
-    JsonRefs.resolveRefs(definition, options.loaderOptions || {}, function (err, resolved, metadata) {
+    JsonRefs.resolveRefs(definition, jsonRefsOptions, function (err, resolved, metadata) {
       /* istanbul ignore if */
       if (err) {
         reject(err);

samples/2.0/refs/info.yaml

@@ -0,0 +1,12 @@
+description: "This is a sample server Petstore server.  You can find out more about\
+  \ Swagger at <a href=\"http://swagger.io\">http://swagger.io</a> or on irc.freenode.net,\
+  \ #swagger.  For this sample, you can use the api key \"special-key\" to test\
+  \ the authorization filters"
+version: "1.0.0"
+title: "Swagger Petstore"
+termsOfService: "http://helloreverb.com/terms/"
+contact:
+  email: "apiteam@swagger.io"
+license:
+  name: "Apache 2.0"
+  url: "http://www.apache.org/licenses/LICENSE-2.0.html"

samples/2.0/refs/models.yaml

@@ -0,0 +1,118 @@
+Order:
+  properties:
+    id:
+      type: "integer"
+      format: "int64"
+    petId:
+      type: "integer"
+      format: "int64"
+    quantity:
+      type: "integer"
+      format: "int32"
+    shipDate:
+      type: "string"
+      format: "date-time"
+    status:
+      type: "string"
+      description: "Order Status"
+      enum:
+      - "placed"
+      - "approved"
+      - "delivered"
+    complete:
+      type: "boolean"
+      default: false
+  type: "object"
+  xml:
+    name: "Order"
+User:
+  properties:
+    id:
+      type: "integer"
+      format: "int64"
+    username:
+      type: "string"
+    firstName:
+      type: "string"
+    lastName:
+      type: "string"
+    email:
+      type: "string"
+    password:
+      type: "string"
+    phone:
+      type: "string"
+    userStatus:
+      type: "integer"
+      format: "int32"
+      description: "User Status"
+  type: "object"
+  xml:
+    name: "User"
+Category:
+  properties:
+    id:
+      type: "integer"
+      format: "int64"
+    name:
+      type: "string"
+  type: "object"
+  xml:
+    name: "Category"
+Tag:
+  properties:
+    id:
+      type: "integer"
+      format: "int64"
+    name:
+      type: "string"
+  type: "object"
+  xml:
+    name: "Tag"
+Pet:
+  required:
+  - "name"
+  - "photoUrls"
+  properties:
+    id:
+      type: "integer"
+      format: "int64"
+    category:
+      $ref: "#/definitions/Category"
+    name:
+      type: "string"
+      example: "doggie"
+    photoUrls:
+      type: "array"
+      xml:
+        name: "photoUrl"
+        wrapped: true
+      items:
+        type: "string"
+    tags:
+      type: "array"
+      xml:
+        name: "tag"
+        wrapped: true
+      items:
+        $ref: "#/definitions/Tag"
+    status:
+      type: "string"
+      description: "pet status in the store"
+      enum:
+      - "available"
+      - "pending"
+      - "sold"
+  type: "object"
+  xml:
+    name: "Pet"
+ApiResponse:
+  properties:
+    code:
+      type: "integer"
+      format: "int32"
+    type:
+      type: "string"
+    message:
+      type: "string"
+  type: "object"

samples/2.0/refs/paths.yaml

@@ -0,0 +1,516 @@
+/pet:
+  post:
+    tags:
+    - "pet"
+    summary: "Add a new pet to the store"
+    description: ""
+    operationId: "addPet"
+    consumes:
+    - "application/json"
+    - "application/xml"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - in: "body"
+      name: "body"
+      description: "Pet object that needs to be added to the store"
+      required: true
+      schema:
+        $ref: "#/definitions/Pet"
+    responses:
+      405:
+        description: "Invalid input"
+  put:
+    tags:
+    - "pet"
+    summary: "Update an existing pet"
+    description: ""
+    operationId: "updatePet"
+    consumes:
+    - "application/json"
+    - "application/xml"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - in: "body"
+      name: "body"
+      description: "Pet object that needs to be added to the store"
+      required: true
+      schema:
+        $ref: "#/definitions/Pet"
+    responses:
+      400:
+        description: "Invalid ID supplied"
+      404:
+        description: "Pet not found"
+      405:
+        description: "Validation exception"
+/pet/findByStatus:
+  get:
+    tags:
+    - "pet"
+    summary: "Finds Pets by status"
+    description: "Multiple status values can be provided with comma seperated strings"
+    operationId: "findPetsByStatus"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "status"
+      in: "query"
+      description: "Status values that need to be considered for filter"
+      required: true
+      type: "array"
+      items:
+        type: "string"
+        enum:
+        - "available"
+        - "pending"
+        - "sold"
+        default: "available"
+      collectionFormat: "multi"
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          type: "array"
+          items:
+            $ref: "#/definitions/Pet"
+      400:
+        description: "Invalid status value"
+/pet/findByTags:
+  get:
+    tags:
+    - "pet"
+    summary: "Finds Pets by tags"
+    description: "Muliple tags can be provided with comma seperated strings. Use\
+      \ tag1, tag2, tag3 for testing."
+    operationId: "findPetsByTags"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "tags"
+      in: "query"
+      description: "Tags to filter by"
+      required: true
+      type: "array"
+      items:
+        type: "string"
+      collectionFormat: "multi"
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          type: "array"
+          items:
+            $ref: "#/definitions/Pet"
+      400:
+        description: "Invalid tag value"
+/pet/{petId}:
+  parameters:
+    - name: "petId"
+      in: "path"
+      description: "ID of pet to return"
+      required: true
+      type: "integer"
+      format: "int64"
+  get:
+    tags:
+      - "pet"
+    summary: "Find pet by ID"
+    description: "Returns a single pet"
+    operationId: "getPetById"
+    produces:
+      - "application/xml"
+      - "application/json"
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          $ref: "#/definitions/Pet"
+      400:
+        description: "Invalid ID supplied"
+      404:
+        description: "Pet not found"
+  post:
+    tags:
+      - "pet"
+    summary: "Updates a pet in the store with form data"
+    description: ""
+    operationId: "updatePetWithForm"
+    consumes:
+      - "application/x-www-form-urlencoded"
+    produces:
+      - "application/xml"
+      - "application/json"
+    parameters:
+      - name: "name"
+        in: "formData"
+        description: "Updated name of the pet"
+        required: false
+        type: "string"
+      - name: "status"
+        in: "formData"
+        description: "Updated status of the pet"
+        required: false
+        type: "string"
+    responses:
+      405:
+        description: "Invalid input"
+  delete:
+    tags:
+    - "pet"
+    summary: "Deletes a pet"
+    description: ""
+    operationId: "deletePet"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "api_key"
+      in: "header"
+      description: ""
+      required: false
+      type: "string"
+      default: ""
+    responses:
+      400:
+        description: "Invalid pet value"
+/pet/{petId}/uploadImage:
+  post:
+    tags:
+    - "pet"
+    summary: "uploads an image"
+    description: ""
+    operationId: "uploadFile"
+    consumes:
+    - "multipart/form-data"
+    produces:
+    - "application/json"
+    parameters:
+    - name: "petId"
+      in: "path"
+      description: "ID of pet to update"
+      required: true
+      type: "integer"
+      format: "int64"
+    - name: "additionalMetadata"
+      in: "formData"
+      description: "Additional data to pass to server"
+      required: false
+      type: "string"
+    - name: "file"
+      in: "formData"
+      description: "file to upload"
+      required: false
+      type: "file"
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          $ref: "#/definitions/ApiResponse"
+/store/inventory:
+  get:
+    tags:
+    - "store"
+    summary: "Returns pet inventories by status"
+    description: "Returns a map of status codes to quantities"
+    operationId: "getInventory"
+    produces:
+    - "application/json"
+    parameters: []
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          type: "object"
+          additionalProperties:
+            type: "integer"
+            format: "int32"
+    security:
+    - api_key: []
+/store/order:
+  post:
+    tags:
+    - "store"
+    summary: "Place an order for a pet"
+    description: ""
+    operationId: "placeOrder"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - in: "body"
+      name: "body"
+      description: "order placed for purchasing the pet"
+      required: true
+      schema:
+        $ref: "#/definitions/Order"
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          $ref: "#/definitions/Order"
+      400:
+        description: "Invalid Order"
+    security:
+      - api_key: []
+/store/order/{orderId}:
+  get:
+    tags:
+    - "store"
+    summary: "Find purchase order by ID"
+    description: "For valid response try integer IDs with value <= 5 or > 10. Other\
+      \ values will generated exceptions"
+    operationId: "getOrderById"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "orderId"
+      in: "path"
+      description: "ID of pet that needs to be fetched"
+      required: true
+      type: "string"
+      maximum: 5.0
+      minimum: 1.0
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          $ref: "#/definitions/Order"
+      400:
+        description: "Invalid ID supplied"
+      404:
+        description: "Order not found"
+    security:
+      - api_key: []
+  delete:
+    tags:
+    - "store"
+    summary: "Delete purchase order by ID"
+    description: "For valid response try integer IDs with value < 1000. Anything\
+      \ above 1000 or nonintegers will generate API errors"
+    operationId: "deleteOrder"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "orderId"
+      in: "path"
+      description: "ID of the order that needs to be deleted"
+      required: true
+      type: "string"
+      minimum: 1.0
+    responses:
+      400:
+        description: "Invalid ID supplied"
+      404:
+        description: "Order not found"
+    security:
+      - api_key: []
+/user:
+  post:
+    tags:
+    - "user"
+    summary: "Create user"
+    description: "This can only be done by the logged in user."
+    operationId: "createUser"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - in: "body"
+      name: "body"
+      description: "Created user object"
+      required: true
+      schema:
+        $ref: "#/definitions/User"
+    responses:
+      default:
+        description: "successful operation"
+    security:
+      - api_key: []
+/user/createWithArray:
+  post:
+    tags:
+    - "user"
+    summary: "Creates list of users with given input array"
+    description: ""
+    operationId: "createUsersWithArrayInput"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - in: "body"
+      name: "body"
+      description: "List of user object"
+      required: true
+      schema:
+        type: "array"
+        items:
+          $ref: "#/definitions/User"
+    responses:
+      default:
+        description: "successful operation"
+    security:
+      - api_key: []
+/user/createWithList:
+  post:
+    tags:
+    - "user"
+    summary: "Creates list of users with given input array"
+    description: ""
+    operationId: "createUsersWithListInput"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - in: "body"
+      name: "body"
+      description: "List of user object"
+      required: true
+      schema:
+        type: "array"
+        items:
+          $ref: "#/definitions/User"
+    responses:
+      default:
+        description: "successful operation"
+    security:
+      - api_key: []
+/user/login:
+  get:
+    tags:
+    - "user"
+    summary: "Logs user into the system"
+    description: ""
+    operationId: "loginUser"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "username"
+      in: "query"
+      description: "The user name for login"
+      required: true
+      type: "string"
+    - name: "password"
+      in: "query"
+      description: "The password for login in clear text"
+      required: true
+      type: "string"
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          type: "string"
+        headers:
+          X-Rate-Limit:
+            type: "integer"
+            format: "int32"
+            description: "calls per hour allowed by the user"
+          X-Expires-After:
+            type: "string"
+            format: "date-time"
+            description: "date in UTC when toekn expires"
+      400:
+        description: "Invalid username/password supplied"
+    security:
+      - api_key: []
+/user/logout:
+  get:
+    tags:
+    - "user"
+    summary: "Logs out current logged in user session"
+    description: ""
+    operationId: "logoutUser"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters: []
+    responses:
+      default:
+        description: "successful operation"
+    security:
+      - api_key: []
+/user/{username}:
+  get:
+    tags:
+    - "user"
+    summary: "Get user by user name"
+    description: ""
+    operationId: "getUserByName"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "username"
+      in: "path"
+      description: "The name that needs to be fetched. Use user1 for testing. "
+      required: true
+      type: "string"
+    responses:
+      200:
+        description: "successful operation"
+        schema:
+          $ref: "#/definitions/User"
+      400:
+        description: "Invalid username supplied"
+      404:
+        description: "User not found"
+    security:
+      - api_key: []
+  put:
+    tags:
+    - "user"
+    summary: "Updated user"
+    description: "This can only be done by the logged in user."
+    operationId: "updateUser"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "username"
+      in: "path"
+      description: "name that need to be deleted"
+      required: true
+      type: "string"
+    - in: "body"
+      name: "body"
+      description: "Updated user object"
+      required: true
+      schema:
+        $ref: "#/definitions/User"
+    responses:
+      400:
+        description: "Invalid user supplied"
+      404:
+        description: "User not found"
+    security:
+      - api_key: []
+  delete:
+    tags:
+    - "user"
+    summary: "Delete user"
+    description: "This can only be done by the logged in user."
+    operationId: "deleteUser"
+    produces:
+    - "application/xml"
+    - "application/json"
+    parameters:
+    - name: "username"
+      in: "path"
+      description: "The name that needs to be deleted"
+      required: true
+      type: "string"
+    responses:
+      400:
+        description: "Invalid username supplied"
+      404:
+        description: "User not found"
+    security:
+      - api_key: []

samples/2.0/swagger-relative-refs.yaml

@@ -0,0 +1,46 @@
+---
+swagger: "2.0"
+info:
+  # Dot reference
+  $ref: './refs/info.yaml'
+host: "petstore.swagger.io"
+basePath: "/v2"
+tags:
+- name: "pet"
+  description: "Everything about your Pets"
+  externalDocs:
+    description: "Find out more"
+    url: "http://swagger.io"
+- name: "store"
+  description: "Access to Petstore orders"
+- name: "user"
+  description: "Operations about user"
+  externalDocs:
+    description: "Find out more about our store"
+    url: "http://swagger.io"
+schemes:
+- "http"
+paths:
+  # No dot reference
+  $ref: 'refs/paths.yaml'
+securityDefinitions:
+  petstore_auth:
+    type: "oauth2"
+    authorizationUrl: "http://petstore.swagger.io/api/oauth/dialog"
+    flow: "implicit"
+    scopes:
+      write:pets: "modify pets in your account"
+      read:pets: "read your pets"
+  api_key:
+    type: "apiKey"
+    name: "api_key"
+    in: "header"
+security:
+  - petstore_auth:
+    - "read:pets"
+    - "write:pets"
+definitions:
+  $ref: './refs/models.yaml'
+externalDocs:
+  description: "Find out more about Swagger"
+  url: "http://swagger.io"

test/helpers.js

@@ -29,7 +29,10 @@ var fs = require('fs');
 var path = require('path');
 
 var app = connect();
+var infoYaml = fs.readFileSync(path.resolve(__dirname, '../samples/2.0/refs/info.yaml'), 'utf-8');
+var pathsYaml = fs.readFileSync(path.resolve(__dirname, '../samples/2.0/refs/paths.yaml'), 'utf-8');
 var swaggerYaml = fs.readFileSync(path.resolve(__dirname, '../samples/2.0/swagger.yaml'), 'utf-8');
+var swaggerRelRefsYaml = fs.readFileSync(path.resolve(__dirname, '../samples/2.0/swagger-relative-refs.yaml'), 'utf-8');
 
 app.use(function (req, res, next) {
   res.setHeader('Access-Control-Allow-Origin', '*');
@@ -43,11 +46,29 @@ app.use(function (req, res, next) {
 
 app.use(function (req, res) {
   switch (req.url) {
+  case '/refs/info.yaml':
+    res.setHeader('Content-Type', 'application/x-yaml');
+    res.statusCode = 200;
+    res.end(infoYaml);
+
+    break;
+  case '/refs/paths.yaml':
+    res.setHeader('Content-Type', 'application/x-yaml');
+    res.statusCode = 200;
+    res.end(pathsYaml);
+
+    break;
   case '/swagger.yaml':
     res.setHeader('Content-Type', 'application/x-yaml');
     res.statusCode = 200;
     res.end(swaggerYaml);
 
+    break;
+  case '/swagger-relative-refs.yaml':
+    res.setHeader('Content-Type', 'application/x-yaml');
+    res.statusCode = 200;
+    res.end(swaggerRelRefsYaml);
+
     break;
   default:
     res.writeHead(404);

test/test-2.0.js

@@ -3507,5 +3507,20 @@ describe('sway (Swagger 2.0)', function () {
         })
         .then(done, done);
     });
+
+    it('should support relative references (and to YAML files) (Issue 17)', function (done) {
+      swaggerApi.create({
+        definition: 'http://localhost:44444/swagger-relative-refs.yaml'
+      })
+        .then(function () {
+          assert.ok(_.isUndefined(swagger.resolved.info.$ref));
+          assert.ok(Object.keys(swagger.resolved.definitions).length > 1);
+          assert.ok(Object.keys(swagger.resolved.paths).length > 1);
+          assert.equal(swagger.resolved.info.title, 'Swagger Petstore');
+          assert.ok(_.isPlainObject(swagger.resolved.definitions.Pet));
+          assert.ok(_.isPlainObject(swagger.resolved.paths['/pet/{petId}'].get));
+        })
+        .then(done, done);
+    });
   });
 });