apidoc/README.md

Apidoc

A code utility to manage your API:s, purely derrived from code (doc-comments).

Trivial example

// @apidoc TYPE User.Token
// [readonly] [auth]
// 
// A JWT token used to verify identity at secured endpoints.
//
// ## Schema
// string.jwt
//
// ## Examples
// 
// ```
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30
// ```
type Token = string;

// @apidoc POST /auth/register Sign-in as user `User.login`
// 
// Using credentials and details, request that a `User` be created and stored,
// returning a `User.token`.
// 
// ## Body JSON
// username: string.ascii(max: 32) [unique] [example = `tommylive`]
// email: string.email The email to use when authenticating the user.
// password: string(min: 8) [sendonly] 
//    A plain-text password to hash and store for authentication.
// 
//    Password criteria:
//    - >8 characters
//    - >1 uppercase ascii letter
//    - >1 symbol, defined as any non-ascii-alphanumeric character 
// display_name?: string(max: 32) [example = `Tommy`]
//    An alternative name to show instead of the username
// 
// ## Responses
// ### 200 User created JSON
// 
// The user passed checks and was created.
// 
// token: User.Token Token to identify as the newly created user
// 
// ### 400 Invalid payload
// ### 409 Username taken
export async function processRegister(req: Request, res: Response) {
    // ...
}