harkerdev-documentation-protocol v1.0.3

koa-documentation-protocol

Parses comments on koa controllers to produce documentation. This requires Koa and TypeScript. File placement does not matter.

npm install harkerdev-documentation-protocol -g

Documentation Protocol

The documentation protocol as so, per each controller.

import Koa, { Context } from 'koa'
import Router from 'koa-router'

const app = new Koa()

// typed response
interface TypedCtx<T> extends Context {
    body: T
}

// typed POST body
interface BodiedRequest<T> extends Request {
    body: T|null
}
interface BodiedCtx<T> extends Context {
    request: BodiedRequest<T>
}

/**
 * Router title
 *
 * Router description
 * **bold** - we support markdown
 *
 * @route /path/
 */
const router = new Router()

// ...

interface ComplicatedResponse {
    // ...
}

/**
 * Route title
 *
 * Route description
 *
 * @query {type} queryParam description
 * @param {string} urlParam description
 *
 * @response {ComplicatedResponse} 200 condition
 * @response {text/plain} 400 condition
 *  Text based response
 *
 * @body {BodyType} {application/json}
 */
router.get('/path/:urlParam', async (ctx: TypedCtx<ComplicatedResponse|string>) => {
    const urlParam: string = ctx.request.params.urlParam;
    let res: ComplicatedResponse;
    // ...
    if (err) {
        ctx.status = 400;
        ctx.body = 'There was an error';
    }
    else {
        // by default, ctx.status = 200
        ctx.body = res;
    }
})

Config

In the same directory that the tsconfig.json is in, create a config file called docconfig.json.

Example

{
    "output": "./api.apib",
    "host": "greeter.harkerdev.com",
    "title": "hGreet API",
    "description": "Top-level description of the API! Yay!",
    "defaults": {
        "string": "abcd",
        "number": 1234,
        "boolean": true,
        "jsonKey": "key"
    },
    "examples": {
        "response": {
            "firstname": "John",
            "lastname": "Doe"
        },
        "param": {
            "firstname": "John",
            "lastname": "Doe"
        },
        "all": {
            "firstname": "John",
            "lastname": "Doe"
        }
    },
    "afterHook": "aglio --theme-variables flatly --theme-template triple -i ./api.apib -o ./api.html"
}

Description

When creating an example query and URL parameter examples, the compiler will use the examples given by examples.all and examples.param as values for each parameter. If not given, the compiler will use the value of defaults.string.

When creating an example response Body (in JSON), the compiler will use examples given by examples.all and examples.response, filling out the Schema given in the comment. If the examples are not defined, the default for the type.

Running

Once installed, change the working directory to the same one as the docconfig.json. Run the command hdoc. An API Blueprint will have been produced, and then you can run something to convert that into HTML (e.g., aglio).

You can also use it with multiple options

For example, to run with the configuration docconfig2.json in watch mode, you would run the command hdoc -p docconfig2.json -w .