How to generate API html documentation from mocha BDD tests?

Question

I worked on a project with Spring Boot java framework where guys automated API docs generation. Every time you run BDD/Integration style tests, there was api blue print file created out from mocha tests. Then it ran generate-html-from-api blueprint. I liked this approach as it has two advantages:

1) API docs are always correct and up-to-date 
2) saves time, because no need to write another documentation file (like apidoc).

Has anyone tried and has working example for node projects? I found api-doc-test plugin, however its documentation is limited. ? Ideally, I would like just to run:

mocha --recursive

Which would generate api-doc.html and place under test/tmp/.

I have looked at swagger but I really don't want to specify endpoint information twice and it would really be awesome just write once in BDD tests and have double result (tests + docs) at the same time.

FWIW we haven't created API Blueprint to be generated from. Instead we have built it to be a testable contract of what API should be. That is why we have built https://github.com/apiaryio/dredd so you can test your implementation against its contract (API Blueprint). /I am the author of API Blueprint/ — Zdenek, Jul 05 '16 at 15:43
@Zdenek Thanks, that changes my picture! For small startup it's worth to write only one type of tests, otherwise it's too expensive. Therefore can I write whole BDD/Integration tests with API blueprint + Dredd instead of using mocha? — Centurion, Jul 05 '16 at 15:50
If that is sufficient for your scenario then yes you can (hard to judge from the outside ) — Zdenek, Jul 18 '16 at 13:40

score 0 · Answer 1 · answered Mar 04 '17 at 20:55

https://github.com/stackia/test2doc.js

I'm working on this project, which enables generating documents (currently only API blueprint) from BDD tests, just exactly what you need.

Test code example:

const doc = require('test2doc')
const request = require('supertest') // We use supertest as the HTTP request library
require('should') // and use should as the assertion library

// For Koa, you should exports app.listen() or app.callback() in your app entry
const app = require('./my-express-app.js')

after(function () {
  doc.emit('api-documentation.apib')
})

doc.group('Products').is(doc => {
  describe('#Products', function () {
    doc.action('Get all products').is(doc => {
      it('should get all products', function () {
        // Write specs towards your API endpoint as you would normally do
        // Just decorate with some utility methods
        return request(app)
          .get(doc.get('/products'))
          .query(doc.query({
            minPrice: doc.val(10, 'Only products of which price >= this value should be returned')
          }))
          .expect(200)
          .then(res => {
            body = doc.resBody(res.body)
            body.desc('List of all products')
              .should.not.be.empty()
            body[0].should.have.properties('id', 'name', 'price')
            body[0].price.desc('Price of this product').should.be.a.Number
          })
      })
    })
  })
})

How to generate API html documentation from mocha BDD tests?

1 Answers1