How to generate apidoc automatically for existing sails js project?

user_3815531 0
Viewed 1732

I am working on sails js project. How can i generate api documentation automatically for all the existing apis (With its JSON request and response)?

sails.js
3 Answers

I'm using APIdoc for all my Sails projects. This is the way I do it:

First install apidoc and rimraf as development deps:

npm install apidoc rimraf --save-dev

Then edit your package json and add script to create apidoc:

...package.json file
"scripts": {
    "docs": "rimraf public/docs && apidoc -i config/ -o public/docs",
    "start": "NODE_ENV=production node app.js"
  },
  "dependencies": {
... rest of package.json file

Of course, public/docs can be any folder you wish to put docs in... I'm using public/docs

Next, just add apidoc specific comments inside your config/routes.js or if you wish to write comments inside controllers, change upper script to run -i /api/controllers instead of -i /config

One bonus trick that I use is serving docs directly with sails so its available on localhost:1337/docs by editing .sailsrc file and adding this:

{
  "generators": {
    "modules": {}
  },
  "hooks": {
  },
  "paths": {
    "public": "public" //name of the folder where all my public assets are (including docs)
  }
}

Whenever you want fresh copy of docs, just run:

npm run docs

You could also automatize this by adding docs generation inside start script inside package.json or even inside config/bootstrap.js. But I found it much better by manually calling docs when I need it. It speeds up lift process.

EDIT: forgot to mention that you can pass apidoc configuration inside package.json file also:

...package.json file

  "main": "app.js",
  "repository": {
    "type": "git",
    "url": "repo url..."
  },
  "apidoc": {
    "title": "My documentation title",
    // you can use all other config options here: http://apidocjs.com/#configuration
  },
  "author": "some guy",
  "license": ""
}

...rest of package.json file
user_20398460
user_43393350

Are you trying to generate the API doc with the structure of the response that you defined in your personalised actions? From my experience, the only way that I was able to do this is by using hand written comments in each controller. I was able to force an API doc with hypermedia responses, instead of just the basic Model for each controller. If there's another way of doing this, please do share.

user_45721020
Related