routedoc — documentation for routes.

routedoc is a tool for documenting and generating urls.

Motivation

Urls are important and having a tool that allows them to be documented in one place helps developers maintain and evolve them as their site/app grows and changes. Many backend frameworks have their own routing built-in, but rarely can you use those routes in other frameworks, other backends, or even on the client-side. The goal of this project is to provide a flexible and human-readable format to document urls that can be used by various clients, backends, and environments.

Installation

To install and use as a module in your nodejs toolchain, run:

npm install routedoc

To install as a command line program, run:

npm install routedoc -g

Example

/**
 * Api endpoint for searching the database
 * @name api-search
 * @param {string} q - text to query for.
 * @returns {SearchResultsJson}
 */
GET /api/:table/search

Running the above through routedoc, like:

routedoc --conf ./routes

-- or --

routedoc < ./routes

will generate the following JSON:

[{
  "method": "GET",
  "name": "api-search",
  "doc": "Api endpoint for searching the database",
  "path": {
    "value": "/api/:table/search"
  },
  "params": {
    "q": {
      "doc": "text to query for.",
      "type": {
        "type": "NameExpression",
        "name": "string"
      }
    },
    "table": {
      "type": {
        "type": "NameExpression",
        "name": "string"
      },
      "doc": null
    }
  },
  "returns": {
    "type": {
      "type": "NameExpression",
      "name": "SearchResultsJson"
    },
    "doc": null
  },
  "tags": {}
}]

From there, it's up to you what you do with the JSON. You can transform it in to something that your framework of choice consumes, generate html docs, automatically create HTTP acceptance tests, or use one of the libraries below.

See more examples here.

Libraries

• Express
• Gulp
• Client-side (coming soon)
• ...?

TODO

• [ ] Support multiple route files
• [ ] Api for generating urls from a route (e.g., routedoc.toUrl('api-search', { q: 'routedoc'}) => '/search?q=routedoc')
  • Note this will probably exist in it's own repo.
• [ ] ...?

License

MIT