api-docs.yml

# api-docs/yaml/api-docs.yml

apiVersion: 1.0.0
swaggerVersion: "1.2"
apis: 
  - path: /books
    description: Books API
authorizations: 
  apiKey: 
    type: apiKey
    passAs: header
info: 
  title: My custom API
  description: "<strong>Great</strong> APIs by Great People.\n"
  termsOfServiceUrl: "http://example.com/terms"
  contact: "support@example.com"
  license: Apache 2.0
  licenseUrl: "http://www.apache.org/licenses/LICENSE-2.0.html"

books.yml

# api-docs/yaml/books.yml

apiVersion: 1.0.0
swaggerVersion: "1.2"
basePath: "/v1"
resourcePath: /books
produces: 
  - application/json
apis: 
  - path: "/books/{id}"
    operations:
      - method: GET
        summary: Retrieve a book, along with its metadata and options
        notes: Returns all available data if secretKey is supplied, otherwise returns only the public record.
        type: Book
        nickname: getBookById
        produces: 
          - application/json
        parameters: 
          - name: id
            description: ID of the book to fetch
            required: true
            allowMultiple: false
            type: string
            paramType: path
          - name: secretKey
            description: Secret key for the request
            required: false
            allowMultiple: false
            type: string
            paramType: query
        responseMessages: 
          - code: 404
            message: Book not found

models: 
  BookChapter:
    id: BookChapter
    title: Chapter
    type: object
    description: "A chapter within the book, to support displaying a table-of-contents."
    required:
      - title
    properties: 
      title:
        type: string
        description: "The title of the chapter"
  Book:
    id: Book
    title: Book
    type: object
    description: "A Book record with optional chapters."
    required: 
      - title
    properties: 
      id: 
        type: string
        description: "Unique ID for this book"
      title:
        type: string
        description: "Book title"
      author:
        type: string
        description: "Author name"
      chapters:
        type: array
        description: "One or more Chapters to list in a TOC"
        items:
          $ref: BookChapter

exec.js

// grunt/exec.js

module.exports = {
    compile_apidocs: {
        command: 'node yml2swagger.js api-docs/yaml api-docs/json',
    },
    mocha_test: {
        command: 'mocha -R spec --recursive test',
    },
};

gistfile1.txt

// tests/books/01-samples.js

var request = require('supertest')
  , app = require('../../app')
  , chai = require('chai')
  , expect = chai.expect
  , chaiHttp = require('chai-http')
  , fs = require('fs');

chai.use(require('chai-json-schema'));

var api = require(process.cwd() + '/api-docs/json/books.yml.json');
chai.tv4.addSchema('Book', api.models.Book);
chai.tv4.addSchema('BookChapter', api.models.BookChapter);

var getJSON = function(filename) {
    var data = fs.readFileSync(process.cwd() + filename);
    return JSON.parse(data);
};

var samples = [
    { id: 'SAMPLE-BOOK',    file: 'sample-book.json',    },
];

describe('Books API: 01. Samples', function() {
    samples.map(function(sample) {
        /* TEST: Sample File */
        describe(sample.id, function() {
            it('should have a valid Schema', function(done) {
                var data = getJSON('/data/books/' + sample.file);
                expect(data).to.be.jsonSchema('Book');

                done();
            });
        });
    });
});

Gruntfile.js

'use strict';

var request = require('request');

module.exports = function (grunt) {
  require('time-grunt')(grunt);
  require('load-grunt-tasks')(grunt);

  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    exec: require('./grunt/exec.js'),
    mocha: require('./grunt/mocha.js'),
  });
};

sample-book.json

{
  "id": "12-456-3788-0",
  "title": "My First Book",
  "author": "Me",
  "chapters": [
    {
      "title": "First Chapter"
    },
    {
      "title": "Second Chapter"
    },
    {
      "title": "It's a Short Book"
    }
  ]
}