Parses comments on koa controllers to produce documentation. This requires Koa and TypeScript. File placement does not matter.
npm install harkerdev-documentation-protocol -g
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;
}
})
In the same directory that the tsconfig.json
is in, create a config file called docconfig.json
.
{
"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"
}
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.
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
.