New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ignore @apiIgnore #27

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

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

This comment has been minimized.

Show comment
Hide comment
@rottmann

rottmann Oct 13, 2015

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) );
Member

rottmann commented Oct 13, 2015

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

This comment has been minimized.

Show comment
Hide comment
@woutrbe

woutrbe 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 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

This comment has been minimized.

Show comment
Hide comment
@woutrbe

woutrbe 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 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

This comment has been minimized.

Show comment
Hide comment
@anddimario

anddimario Nov 30, 2015

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

Best regards

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

Best regards

@woutrbe

This comment has been minimized.

Show comment
Hide comment
@woutrbe

woutrbe 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.

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

This comment has been minimized.

Show comment
Hide comment
@anddimario

anddimario Dec 1, 2015

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

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

This comment has been minimized.

Show comment
Hide comment
@avshelestov

avshelestov Mar 14, 2016

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!

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

This comment has been minimized.

Show comment
Hide comment
@BreaGaudioso

BreaGaudioso May 10, 2016

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!

BreaGaudioso commented May 10, 2016

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!

@woutrbe woutrbe closed this Feb 16, 2017

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