kwhitley / itty-router-help

Help middleware for itty-router

Experimental library to make browsable, documented REST APIs extremely easy (requires itty-router). This is currently in pre-alpha, so use with care - the API will certainly be evolving. While itty-router API code tends to be very simple/readable, I still found myself forgeting endpoints and having to open code to see what was available. This aims to solve that, by allowing APIs to be explored in-place, live in your browser.

Features

• easily add documentation to specific routes or indexes
• auto-documents method, route, params, demo links (on GET routes without params)
• add anything you like into the help notes (format agnostic)

How to Use

1. create middleware via createHelp(router) function
2. use withHelp middleware on individual routes
3. use withHelpIndex middleware on upstream index route to summarize
4. add ?help to any documented route or index to see live documentation

Installation

npm install itty-router@next itty-router-help

Example

import { 
  Router,
  withParams,
} from 'itty-router'
import { withHelp, withHelpIndex } from 'itty-router-help'

// create a new Router
const router = Router({ base: '/v1' })   

router
  // add some global middleware
  .all('*', withParams) 
  
  // embed the help index upstream
  .get('/', withHelpIndex(router))

  .get('/simple/endpoint',
    withHelp(),
    () => 'Default help example'
  }

  // It can be this easy... this will document the method, route, and each param
  .get('/foo/bar/:baz/:extra?',
    withHelp(),
    () => 'Foo Bar Baz!'
  )

  // This route help will only be accessible directly, not visible in the index.
  .get('/secret/route',
    withHelp({ indexed: false })
    () => ''
  )

  // Add any payload you like... this will be merged with the automatic output.
  .post('/add/anything',
    withHelp({
      'description': 'Adding a description to your help routes is a nice touch.',
      'query_params': {
        'awesome': {
          'description': 'Make things awesome!',
          'required': false,
        }
      }
    })
    ({ query }) => query.awesome ? 'AWESOME!' : 'normal'
  )

  // 404 for everything else
  .all('*', () => error(404))

Browsing

// Example: /v1?help
{
  "endpoints": {
    "GET /simple/endpoint", {
      "demo": "/v1/simple/endpoint"
    },
    "GET /foo/bar/:baz/:extra?": {
      "params": {
        "baz": {
          "required": true
        },
        "extra": {
          "required": false
        }
      }
    },
    "POST add/anything": {
      "description": "Adding a description to your help routes is a nice touch.",
      "query_params": {
        "awesome": {
          "description": "Make things awesome!",
          "required": false
        }
      }
    }
  }
}

// Example /v1/secret/route?help
{
  "GET /secret/route": {
    "demo": "/v1/secret/route"
  }  
}

Join the Discussion!

Have a question? Suggestion? Complaint? Want to send me a gift basket?

Join us on Discord!

Testing and Contributing

1. Fork repo
2. Install dev dependencies via yarn
3. Start test runner/dev mode yarn dev
4. Add your code and tests if needed - do NOT remove/alter existing tests
5. Verify that tests pass once minified yarn verify
6. Commit files
7. Submit PR with a detailed description of what you're doing
8. I'll add you to the credits! :)