node package manager

api-doc-test

API Blueprint from Jasmine/Mocha tests

NPM version build status

Generate API Blueprint from BDD-style (Jasmine/Mocha) tests.

Install

npm install --save api-doc-test

Usage

var generateDoc = require('api-doc-test');
 
var header = 'FORMAT: 1A\n' +
  'HOST: https://api.lobsterchat.com/\n\n' +
  '# Lobster Chat API\n\n' +
  'This API provides access to the Lobster Chat messaging service.';
 
generateDoc(header, './**/*test.js', function(err, doc) {
  if (err) throw err;
  console.log(doc);
});

Test Structure

BDD-style tests should follow given structure so API Blueprint can be generated properly.

// This group consists of two resources: /lobsters/ and /lobsters/{id}/. 
describe('Lobsters', function() {
 
  // This resource is for creating and listing lobsters. 
  describe('Lobsters [/lobsters/]', function() {
 
    // Creates a new lobster. 
    describe('Create Lobster [POST]', function() {
 
      // Request (application/json) example/request.json 
      // Response 201 (application/json) example/response.json 
      it('creates a new lobster', function(done) {
 
      });
 
      // Request (application/json) example/missingParameter.request.json 
      // Response 400 (application/json) example/missingParameter.response.json 
      it('returns 400 error if missing parameter', function(done) {
 
      });
    });
  });
});

API Blueprint

The resulting API Blueprint from the example above looks like this.

FORMAT: 1A
HOST: https://api.lobsterchat.com/
 
# Lobster Chat API
 
This API provides access to the Lobster Chat messaging service.
 
# Group Lobsters
 
This group consists of two resources: /lobsters/ and /lobsters/{id}/.
 
## Lobsters [/lobsters/]
 
This resource is for creating and listing lobsters.
 
### Create Lobster [POST]
 
Creates a new lobster.
 
+ Request (application/json)
 
        {
            "name": "John",
            "claws": 2
        }
 
+ Response 201 (application/json)
 
        {
            "id": 1,
            "name": "John",
            "claws": 2
        }
 
+ Request (application/json)
 
        {
            "name": "John"
        }
 
+ Response 400 (application/json)
 
        {
            "error": "Some parameter is missing."
        }

License

MIT © Samir Djellil