bi-service-doc

This bi-service plugin generates documentation (swagger-ui like frontend) for bi-service Apps.
Here is how it works in few steps:

• During service initialization, Apps are fetched from AppManager
• Open API (OAS) REST API specification is generated from static route definitions
• For each App in AppManager, corresponding Doc app (which serves the documentation frontend) is created and pushed into internal AppManager stack
• As Doc apps imlement the same interface of regular App object, the service initialization process continues as it would without any documentation being generated.

USAGE

• Hook up the plugin into your application in your app's index.js file:

const config  = require('bi-config');
const Service = require('bi-service');

//service initialization stuff...
const service = new Service(config);

//...

//hook-up the plugin
require('bi-service-doc');

• Enable automatic Doc app generation in your service config.json5:

{
    apps: {
        appName: {
            // provide the doc configuration section for each app you want
            // the documentation to be generated for
            doc: {
                baseUrl: '127.0.0.1:3000',
                listen: 3000,
                name: 'docs',
                title: 'User API',
                stopOnError: true,
                tryItOut: true
            }
        }
    }
}

From what the docs are generated?

• Router & Route definitions.
• Validation schema definitions provided to the route.validate & route.respondsWith methods.
• Custom Ajv keyword $desc which bi-service provides, can be used to describe individual request/response data properties in user defined Route validation schemas.

  route.respondsWith({ //200 - OK response
      type: 'object',
      properties: {
          is_active: {
              type: 'boolean',
              $desc: 'Whether the user has been online within a period of last 7 days'
          }
      }
  });
  
  //
  route.validate({
      username: {type: 'string'}
  }, 'params');
  

• Possible route error responses can be described also by the route.respondsWith method:

  route.respondsWith(RequestError);
  route.respondsWith(new RequestError({
      apiCode: 'tag.alreadyExists'
      message: 'Tag already exists'
  }));
  route.respondsWith(UnauthorizedError);
  

Also see bi-service Error management