Nearsighted Penguin March

    node-autodoc

    0.0.7 • Public • Published

    node-autodoc

    Coverage Status Build Status

    A test-driven generator for API documentation. Inspired by autodoc and supertest.

    Why need this

    Some people are not happy to maintain the API documentation when dealing with the large project. Then, it causes so many confusions and problems when someone new to use previous APIs.

    This library is to generate a documentation by given the test cases. It renders the API documentation according to the input and output of each http request.

    Work flow

    Example

    There is also an example inside the repo. Check this out!

    Render mode

    Default template

    It renders the documentation using ejs template engine by default.

    Custom template

    If you have better templates, you can specify the templateDir to let AutoDoc render your templates. You may want to check out the default templates first, then design your templates.

    Custom render function

    If you have better idea to render the API doc page, you can also pass a callback in renderPage to make your custom renders.

    agent.renderPage((currentAgent) => {
      // Assemable your render data
      const myRenderData = {
        title: currentAgent.title,
        description: currentAgent.description,
        docMetaCollection: currentAgent.docMetaCollection,
        tableOfContent: currentAgent.docMetaCollection.map((docMeta) => ({
          link: `#${encodeURIComponent(docMeta.title)}`,
          title: docMeta.title,
        })),
      };
      
      // Your render function
      customRender(myRenderData);
    })

    A very common case would be like: Send all the docMetaCollection to your documentation server and generate your own documentation website.

    API

    Most of the usages are same as supertest. Its APIs are really neat and simple.

    The extra APIs this library enhances are below.

    AutoDocAgent

    const agent = new AutoDocAgent(
      app,
      {
        outputFilename: 'users.html',
        title: 'Users API Documentation',
        description: 'A small and simple documentation for how to deal with /users api',
        outputDir,
        templateDir,
      }
    )

    AutoDocAgent

    parameter value
    app Your express app, or koa app
    options Extends from supertest options

    options

    parameter description
    outputFilename The file name of current api document
    outputDir Current api document output directory
    templateDir Ejs template directory. It will use the default template if ignore it
    title Title of current api doc
    description Description of current api doc

    AutoDocAgent.clear

    Clear the given outputDir directory.

    AutoDocAgent.clear(outputDir)

    AutoDocAgent.renderIndex

    Render the home page by given all agents.

    AutoDocAgent.renderIndex({
      title: 'My API Documentation',
      description: 'This is my first documentation for testing, haha~',
      author: 'Haixiang',
      agents,
      outputDir,
      templateDir,
    });
    parameter value
    title Home page title
    description Home page description
    author Author
    agents AutoDocAgent instance array
    outputDir Output directory
    templateDir Ejs template directory. It will use the default template if ignore it

    restful method

    When calling the restful method, it's calling the restful method of supertest. The only difference is the second parameter.

    agent.get('/users', {
      title: 'Fetch all users',
      description: 'To get all user infomation'
    })

    title and description would render as the title and description of current API doc.

    renderPage

    Render current API doc.

    agent.renderPage()

    If you have better idea to render the API doc page, you can also put a callback in there to make your custom renders.

    agent.renderPage((currentAgent) => {
      // Assemable your render data
      const myRenderData = {
        title: currentAgent.title,
        description: currentAgent.description,
        docMetaCollection: currentAgent.docMetaCollection,
        tableOfContent: currentAgent.docMetaCollection.map((docMeta) => ({
          link: `#${encodeURIComponent(docMeta.title)}`,
          title: docMeta.title,
        })),
      };
      
      // Your render function
      customRender(myRenderData);
    })

    Keywords

    none

    Install

    npm i node-autodoc

    DownloadsWeekly Downloads

    1

    Version

    0.0.7

    License

    MIT

    Unpacked Size

    380 kB

    Total Files

    8

    Last publish

    Collaborators

    • seamonster