Skip to content

Latest commit

 

History

History
145 lines (124 loc) · 4.28 KB

README.md

File metadata and controls

145 lines (124 loc) · 4.28 KB

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

Property Type Description
output string The file to output the API Blueprint file to
host string The domain to which the documentation refers
title string The title of the API
description string The description of the purpose of the API
defaults object The default examples to give for parameters and responses
defaults.string string The default string example
defaults.number number The default number example
defaults.boolean boolean The default boolean example
defaults.jsonKey string The default example key
examples object The specific examples to give for parameters and responses
examples.response object The specific examples to give for responses. For each
examples.params object The specific examples to give for parameters
examples.all object The specific examples to give for parameters and responses
afterHook string The command to run after producing the API blueprint

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

Option Description
-h, --help Show help
-p, --project Path to a docconfig.json file describing documentation
-w, --watch Recompile when input files change

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