Ignore @apiIgnore #27

Open
woutrbe opened this Issue Oct 13, 2015 · 8 comments

Projects

None yet

5 participants

@woutrbe
woutrbe commented Oct 13, 2015

Is it possible to have an extra option to be able to ignore @apiIgnore.

My current use case is as follows; I'm building a client facing API, this API also contains private methods that are not open to clients.
So ideally I want to generate two different API docs, one for clients, one for internal use.

Currently private methods are left out by using @apiIgnore Private method, but of course for our internal docs I want those to be included.

@rottmann
Member

If you use a build tool like grunt, you can add a task that filters the api_data.json after apidoc generates the file.

Example api_data.json

{
  {
    "type": "get",
    "url": "/something/",
    "title": "Something",
    "name": "GetSomething",
    "group": "Somegroup",
    "version": "1.0.0",
    "filename": "src/api_something.js"
  },
  {
    "type": "get",
    "url": "/permission/",
    "title": "Permission",
    "name": "GetPermission",
    "group": "Permission",
    "version": "1.0.0",
    "filename": "src/api_permission.js",
    "permission": [
      {
        "name": "private",
        "title": "Private access.",
        "description": "Some description."
      }
    ]
  }
}

Quick example Task:

// Return all api methods, except entries with permission 'private'
var fs = require('fs');
var data = JSON.parse( fs.readFileSync('api_data.json', 'utf8') );

var publicApi = data.filter(function(method) {
    if ( ! method.permission)
        return true;

    var permissions = method.permission.filter( function(permission) {
        return (permission.name && permission.name === 'private');
    });

    return permissions.length === 0;
});

fs.writeFileSync('api_data.json', JSON.stringify(publicApi, null, 2) );
@woutrbe
woutrbe commented Oct 14, 2015

Thanks, that's exactly what I needed.

I created two new grunt tasks, one that filters out private permissions, and another one that just does everything. Works prefect.

@woutrbe woutrbe closed this Oct 14, 2015
@woutrbe
woutrbe commented Oct 15, 2015

It looks that it use api_data.js by default, changing the json file doesn't actually do anything. I can't find anything in the documentation about only using api_data.json to load data from.

@woutrbe woutrbe reopened this Oct 15, 2015
@anddimario

Hi, i'm looking for the same problem, someone found a solution for that?

Best regards

@woutrbe
woutrbe commented Dec 1, 2015

@anddimario Since apidoc generates both a .json and .js file with data, you can simply alter that file to remove unwanted endpoints, that worked for me.

@anddimario

Hi, thanks for your replay, i've used a different system, i've created doc.private.js for private only api and doc.public.js for public, then i've create this grunt task:
apidoc: { dev: { src: "src/", dest: "apidoc-dev/", options: { includeFilters: [ ".*\\.js$" ], excludeFilters: [ "node_modules/" ] } }, prod: { src: "src/", dest: "apidoc-prod/", options: { includeFilters: [ ".*\\.public.js$" ], excludeFilters: [ "node_modules/" ] } } },

Thanks for your time.
Best regards

@avshelestov

If I could add tags to my api methods (@apiTags mobile, private) and later use they to generate in my config file or command (apidoc -i example/ -o doc/ -t mobile). it will be great!

@BreaGaudioso
BreaGaudioso commented May 10, 2016 edited

Hi all,

I am working with the same issue. Has anyone found a way to generate two separate html files (one with all endpoints, one with only public endpoints)?

I was able to build a gulp task which creates a new JSON with the public only endpoint, but I am wondering if there is a way to create two separate html files from inside the same apidoc folder.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment