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, available
App
s are fetched fromAppManager
- Open API (OAS) REST API specification is generated from static route definitions
- For each
App
inAppManager
, corresponding (additional)Doc
http app (which serves the documentation frontend) is created and pushed into internalAppManager
stack - As
Doc
http apps implement the same interface of generic httpApp
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 = ;const Service = ; //service initialization stuff...const service = config; //... //hook-up the plugin;
- 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: 'http://127.0.0.1:3000' listen: 3000 title: 'User API' //optional stopOnError: true //optional //allows us to include hand-crafted API description for each version readme: //optional 'v2.0': 'lib/routes/v2.0/README.md'
From what the docs are generated?
- Router & Route definitions - more specifically
desc
&summary
constructor options. - Validation schema definitions provided to the route.validate & route.respondsWith methods.
- Supported request
content-type(s)
as defined via route.acceptsContentType - Custom
Ajv
keyword$desc
whichbi-service
provides, can be used to describe individual request/response data properties in user definedRoute
validation schemas.route;//route; - Possible route error responses can be described also by the
route.respondsWith
method:route;route;route;
Also see bi-service
Error management