okanjo-app-server-docs

Generate API/route docs automatically

Usage no npm install needed!

<script type="module">
  import okanjoAppServerDocs from 'https://cdn.skypack.dev/okanjo-app-server-docs';
</script>

README

Okanjo Server Documentation Generator

Build Status Coverage Status

Super basic module to generate documentation in Markdown and JSON based on HAPI route tags. You could use this to generate an SDK!

Installing

Add to your project like so:

npm install okanjo-app-server-docs

Note: requires

Note: Use okanjo-app-server-docs@^1.x.x for OkanjoServer 1.x (Hapi 16 and below)

Example Usage

You can see a basic demonstration by running:

node test-app/verify.js

and visiting:

  • http://localhost:3001/docs – Rendered version using Flatdoc + Markdown
  • http://localhost:3001/docs/markdown – Generated markdown
  • http://localhost:3001/docs/json – Generated JSON

DocService(app, server)

Creates a new instance of the documentation service.

  • app – The OkanjoApp instance to bind to
  • server – The OkanjoServer instance to bind to

service.getRouteTable()

Gets the routing table as a serializable object. May include internal information that should not be publically exposed. Does not include ignored or excluded routes.

service.getPublicRouteTable()

Gets only the publicly accessible route definitions. Uses service.getRouteTable for data, and formats for public consumption.

service.generateMarkdown(ignoreUnorganizedRoutes)

Generates a markdown interpretation of the server routes.

  • ignoreUnorganizedRoutes – Whether to include routes that have not been organized into resource groups. Useful to enable in development environments to identify new or missed routes, but disable in production to prevent leaking beta routes.

service.getDocsPageMarkupTemplate()

Returns a sample HTML template that can be used to display the markdown publically.

Extending and Contributing

Our goal is quality-driven development. Please ensure that 100% of the code is covered with testing.

Before contributing pull requests, please ensure that changes are covered with unit tests, and that all are passing.

Testing

To run unit tests and code coverage:

npm run report

This will perform:

  • Unit tests
  • Code coverage report
  • Code linting

Sometimes, that's overkill to quickly test a quick change. To run just the unit tests:

npm test

or if you have mocha installed globally, you may run mocha test instead.