nabeel-ahmad / express-mongoose-docs Goto Github PK

Auto-generated Documentation for Express and Mongoose based APIs

License: Other

CSS 3.34% JavaScript 57.76% HTML 38.90%

express-mongoose-docs's Introduction

express-mongoose-docs

This module will take away the pain of writing API and Data Model documentation for your Express & Mongoose based REST API. It auto-generates API documentation from the code on runtime so the documentation always stays up to date.

Installation

Step 1 : Install

npm install express-mongoose-docs

Step 2 : Configure

Add these lines to your app.js file

var docs = require("express-mongoose-docs");

Make sure the following line comes after all express middleware such as app.use(express.bodyParser());

docs(app, mongoose); // 2nd param is optional

That's it. The Docs web page should be accessible at Your-Base-URL/apiDocs

Example: http://localhost:5000/apiDocs

Screenshots

express-mongoose-docs's People

Contributors

Stargazers

Watchers

Forkers

muslimmunir mogui durgeshnagare simoneb cannonpalms olegdeezus wesleybliss robblovell paranoiasystem zhy1 hetianzhuo yizumi1012xxx jennypavlova johnharris85 devnm21 seyiogunjuyigbe

express-mongoose-docs's Issues

Conditional requirements are listed as required

Mongoose allow functions that return true or false as value for the required key:

    thisIsAField: {
      type: String,
      required: function(value) {
        return whatever ? true : false
      }
    },

However, express-mongoose-docs lists this as a required field. I propose that field requirements that return a function are listed as "conditional" instead of "true".

Duplicate models

In situations where two schemas reuse another schema, the generated documentation shows the reused schema multiple times rather than showing only one instance of that reused schema.

For example, ContextSchema will show twice in the documentation in two different places. (in coffeescript below)

Schema = require('mongoose').Schema
ContextSchema = new Schema(
    {
        name: String,
        sku: { type: String, index: true }
    },
    { strict: false, _id: false }
)
RuleContextSchema = new Schema(
  {
    context: [ContextSchema]
  }
  {strict: false}
)
FactContextSchema = new Schema(
    {
        context: [ContextSchema]
    },
    { strict: false }
)

ContextSchema = new Schema(
    {
        name: [String] # works: shows as 'string []'
        sku: [{ type: String, index: true }] # doesn't work: shows as 'undefined []'
        seller: [{ type: String }] # doesn't work: shows as 'undefined []'
    },
    { strict: false, _id: false }
)

Routes documentation do not respect app.use('/path_to_routes', router);

The following steps may be used to reproduce this issue:

follow the express-general introduction here: http://expressjs.com/starter/generator.html
in myapp follow the express-mongoose-docs introduction here: http://nabeel-ahmad.github.io/express-mongoose-docs/
place docs(app) after app.use('/users', users);
npm start and navigate to http://localhost:3000/apiDocs

In the apiDocs there will be two entries for the get method with path '/'. Expected behaviour is to have a get method for the '/' and '/users' paths.

Any way to turn off model docs

I don't really want to expose the mongoose model docs.

Might be that express-docs and mongoose-docs are 2 different modules. Just a thought.

Great start, looks awesome!!!