├── .eslintrc.js ├── .gitignore ├── .npmignore ├── CHANGELOG.md ├── Gruntfile.example.js ├── Gruntfile.js ├── LICENSE ├── README.md ├── bin └── grunt-apidoc ├── package-lock.json ├── package.json ├── tasks └── apidoc.js └── test └── fixtures └── example.js /.eslintrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | env: { 3 | browser: false, 4 | commonjs: true, 5 | es2021: true, 6 | }, 7 | extends: [ 8 | 'standard', 9 | 'eslint:recommended', 10 | ], 11 | parserOptions: { 12 | ecmaVersion: 12, 13 | }, 14 | env: { 15 | 'browser': false, 16 | 'amd': true, 17 | 'es6': true, 18 | }, 19 | rules: { 20 | 'comma-dangle': ['error', 'always-multiline'], 21 | 'no-extra-parens': ['error', 'all'], 22 | 'quotes': ['error', 'single'], 23 | 'semi': ['error', 'always'], 24 | 'object-shorthand': 'off', 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | tmp/ 3 | npm-debug.log 4 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | .git/ 2 | node_modules/ 3 | test/ 4 | tmp/ 5 | .gitignore 6 | .npmignore 7 | npm-debug.log 8 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 1.0.0 4 | - Update after a hiatus of 7 years. 5 | 6 | ## 0.11.0 7 | - Update for Grunt 1. 8 | 9 | ## 0.10.2 10 | - Update dependencies. 11 | 12 | ## 0.10.1 13 | - Update dependencies. 14 | 15 | ## 0.10.0 16 | - Upgrade to use always the latest version of apiDoc. 17 | 18 | ## 0.9.0 19 | - Upgrade to apiDoc 0.9.x. 20 | 21 | ## 0.8.0 22 | - Upgrade to apiDoc 0.8.x. 23 | 24 | ## 0.7.0 25 | - Upgrade to apiDoc 0.7.x. 26 | 27 | ## 0.6.0 28 | - Upgrade to apiDoc 0.6.x. 29 | 30 | ## 0.5.0 31 | - Upgrade to apiDoc 0.5.x. 32 | 33 | ## 0.4.0 34 | - Upgrade to apiDoc 0.4.x. 35 | 36 | ## 0.3.0 37 | - Upgrade to apiDoc 0.3.x. 38 | 39 | ## 0.2.1 40 | - Remove this.async() (Iolo https://github.com/apidoc/grunt-apidoc/pull/2) 41 | 42 | ## 0.2.0 43 | - Upgrade to apiDoc 0.2.x. 44 | 45 | ## 0.1.2 46 | - Grunt peer dependencies. 47 | 48 | ## 0.1.1 49 | - Change binary Name. 50 | 51 | ## 0.1.0 52 | - Initial release. 53 | -------------------------------------------------------------------------------- /Gruntfile.example.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = function (grunt) { 4 | grunt.initConfig({ 5 | // apidoc configuration 6 | apidoc: { 7 | build: { 8 | src: 'src', 9 | dest: 'tmp/', 10 | options: { 11 | debug: true, 12 | includeFilters: ['.*\\.js$'], 13 | }, 14 | }, 15 | }, 16 | }); 17 | 18 | grunt.loadNpmTasks('grunt-apidoc'); 19 | // Task: build api documentation 20 | grunt.registerTask('default', 'apidoc'); 21 | }; 22 | -------------------------------------------------------------------------------- /Gruntfile.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = function (grunt) { 4 | grunt.initConfig({ 5 | // clear temporary dir 6 | clean: { 7 | test: ['tmp'], 8 | }, 9 | 10 | // apidoc configuration 11 | apidoc: { 12 | test: { 13 | src: 'test/fixtures', 14 | dest: 'tmp/', 15 | options: { 16 | debug: true, 17 | includeFilters: ['.*\\.js$'], 18 | }, 19 | }, 20 | }, 21 | 22 | }); 23 | 24 | // load plugins tasks 25 | grunt.loadTasks('tasks'); 26 | 27 | // Tasks 28 | grunt.loadNpmTasks('grunt-contrib-clean'); 29 | 30 | // Tasks: Test 31 | grunt.registerTask('test', ['clean', 'apidoc']); 32 | }; 33 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2013-2014 inveris OHG 2 | Author Peter Rottmann 3 | Licensed under the MIT license. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # grunt-apidoc 2 | 3 | # Deprecation notice 4 | 5 | Grunt is from the past. Use a script in your package.json now to generate apidoc. This code is broken and won't get fixed. 6 | 7 | 8 | ========================== 9 | 10 | ## About 11 | 12 | Use [Grunt](https://gruntjs.com/) to generate a RESTful API Documentation with [apiDoc](http://apidocjs.com). 13 | 14 | ## Installation 15 | 16 | 1. `npm install grunt-apidoc --save-dev` 17 | 2. Add `grunt.loadNpmTasks('grunt-apidoc');` to `Gruntfile.js` 18 | 19 | ## Configuration 20 | 21 | Add the task to your Gruntfile's **grunt.initConfig**: 22 | 23 | ```javascript 24 | apidoc: { 25 | myapp: { 26 | src: "app/", 27 | dest: "apidoc/" 28 | } 29 | } 30 | ``` 31 | 32 | Use only one src and one dest, apiDoc search in subdirs for files with apidoc-parameters. 33 | 34 | 35 | ### Additional options 36 | 37 | All `apiDoc` options can be used within options-block, see `apidoc -h`. 38 | 39 | * src: Source files directory. 40 | * dest: Destination directory, where the documentation will be created. 41 | * template: Directory with the template files. 42 | * options 43 | * includeFilters: `[ ".*\\.js$" ]` RegEx, which files to parse. 44 | * debug: false Show Debug Output. 45 | * log: true Show Log Output. 46 | * simulate: false Simulation, no files will be written. 47 | 48 | **Example options:** 49 | 50 | **includeFilters** 51 | With `includeFilters` you can define which files apiDoc should include, default `*.js`. 52 | 53 | **debug** 54 | Show verbose information. 55 | 56 | ```javascript 57 | apidoc: { 58 | myapp: { 59 | src: "app/", 60 | dest: "apidoc/", 61 | options: { 62 | debug: true, 63 | includeFilters: [ ".*\\.js$" ], 64 | excludeFilters: [ "node_modules/" ] 65 | } 66 | } 67 | } 68 | ``` 69 | 70 | 71 | 72 | ## Help 73 | 74 | Please visit the main [apiDoc project page on github](https://github.com/apidoc/apidoc) for help and information. 75 | -------------------------------------------------------------------------------- /bin/grunt-apidoc: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | 'use strict'; 4 | 5 | // modules 6 | const path = require('path'); 7 | const grunt = require('grunt'); 8 | 9 | const basePath = path.resolve.bind(null, __dirname, '..'); 10 | 11 | const pkg = require(basePath('package.json')); 12 | 13 | grunt.task.loadTasks(basePath('tasks')); 14 | 15 | // help 16 | grunt.help.queue = [ 17 | 'content', 18 | ]; 19 | 20 | grunt.help.content = function () { 21 | grunt.log.writeln('grunt-init: Create RESTful API Documentation with apidoc. (v' + pkg.version + ')'); 22 | }; 23 | 24 | // version 25 | if (grunt.cli.options.version) { console.log('grunt-init v' + pkg.version); } 26 | 27 | // execute 28 | grunt.cli(); 29 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "grunt-apidoc", 3 | "version": "1.0.0", 4 | "description": "Grunt task to generate a RESTful API Documentation with apidoc", 5 | "author": "Peter Rottmann ", 6 | "license": { 7 | "type": "MIT", 8 | "url": "https://github.com/apidoc/grunt-apidoc/blob/master/LICENSE" 9 | }, 10 | "bin": "bin/grunt-apidoc", 11 | "main": "Gruntfile.js", 12 | "homepage": "http://apidocjs.com", 13 | "repository": { 14 | "type": "git", 15 | "url": "https://github.com/apidoc/grunt-apidoc.git" 16 | }, 17 | "scripts": { 18 | "test": "grunt test" 19 | }, 20 | "keywords": [ 21 | "grunt", 22 | "plugin", 23 | "gruntplugin", 24 | "api", 25 | "apidoc", 26 | "doc", 27 | "documentation", 28 | "rest", 29 | "restful" 30 | ], 31 | "engines": { 32 | "node": ">=16.0.0" 33 | }, 34 | "dependencies": { 35 | "apidoc": "*" 36 | }, 37 | "devDependencies": { 38 | "eslint": "^8.39.0", 39 | "eslint-config-recommended": "^4.1.0", 40 | "eslint-config-standard": "^17.0.0", 41 | "eslint-plugin-node": "^11.1.0", 42 | "grunt-contrib-clean": "^2.0.1" 43 | }, 44 | "peerDependencies": { 45 | "grunt": "^1.6.1" 46 | } 47 | } 48 | -------------------------------------------------------------------------------- /tasks/apidoc.js: -------------------------------------------------------------------------------- 1 | module.exports = function (grunt) { 2 | // modules 3 | const apidoc = require('apidoc'); 4 | 5 | // task 6 | grunt.registerMultiTask('apidoc', 'Create REST-API-Documentation with apidoc', function () { 7 | const config = this.data; 8 | const options = config.options || {}; 9 | 10 | grunt.log.subhead('grunt-apidoc'); 11 | 12 | // options 13 | options.src = config.src; 14 | options.dest = config.dest; 15 | options.template = config.template; 16 | 17 | // execute 18 | const result = apidoc.createDoc(options); 19 | 20 | if (result === false) { 21 | grunt.log.error('grunt-apidoc error: Execution terminated (set \'options: { debug: true }\' in Gruntfile.js for details.'); 22 | return false; 23 | } else { 24 | grunt.log.ok('grunt-apidoc finished.'); 25 | return true; 26 | } 27 | }); 28 | }; 29 | -------------------------------------------------------------------------------- /test/fixtures/example.js: -------------------------------------------------------------------------------- 1 | /** 2 | * For Details and more examples visit http://apidocjs.com 3 | */ 4 | 5 | /** 6 | * @apiDefinePermission admin Admin access rights needed. 7 | * Optionally you can write here further Informations about the permission. 8 | * 9 | * An "apiDefinePermission"-block can have an "apiVersion", so you can attach the block to a specific version. 10 | * 11 | * @apiVersion 0.3.0 12 | */ 13 | 14 | /** 15 | * @apiDefinePermission admin This title is visible in version 0.1.0 and 0.2.0 16 | * @apiVersion 0.1.0 17 | */ 18 | 19 | /** 20 | * @api {get} /user/:id Read data of a User 21 | * @apiVersion 0.3.0 22 | * @apiName GetUser 23 | * @apiGroup User 24 | * @apiPermission admin 25 | * 26 | * @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0. 27 | * 28 | * @apiParam {String} id The Users-ID. 29 | * 30 | * @apiSuccess {String} id The Users-ID. 31 | * @apiSuccess {Date} registered Registration Date. 32 | * @apiSuccess {Date} name Fullname of the User. 33 | * 34 | * @apiError NoAccessRight Only authenticated Admins can access the data. 35 | * @apiError UserNotFound The id of the User was not found. 36 | * 37 | * @apiErrorExample Response (example): 38 | * HTTP/1.1 401 Not Authenticated 39 | * { 40 | * "error": "NoAccessRight" 41 | * } 42 | */ 43 | 44 | /** 45 | * @api {get} /user/:id Read data of a User 46 | * @apiVersion 0.2.0 47 | * @apiName GetUser 48 | * @apiGroup User 49 | * @apiPermission admin 50 | * 51 | * @apiDescription Here you can describe the function. 52 | * Multilines are possible. 53 | * 54 | * @apiParam {String} id The Users-ID. 55 | * 56 | * @apiSuccess {String} id The Users-ID. 57 | * @apiSuccess {Date} name Fullname of the User. 58 | * 59 | * @apiError UserNotFound The id of the User was not found. 60 | */ 61 | 62 | /** 63 | * @api {get} /user/:id Read data of a User 64 | * @apiVersion 0.1.0 65 | * @apiName GetUser 66 | * @apiGroup User 67 | * @apiPermission admin 68 | * 69 | * @apiDescription Here you can describe the function. 70 | * Multilines are possible. 71 | * 72 | * @apiParam {String} id The Users-ID. 73 | * 74 | * @apiSuccess {String} id The Users-ID. 75 | * @apiSuccess {Date} name Fullname of the User. 76 | * 77 | * @apiError UserNotFound The error description text in version 0.1.0. 78 | */ 79 | 80 | /** 81 | * @apiDefineErrorStructure CreateUser 82 | * @apiVersion 0.2.0 83 | * 84 | * @apiError NoAccessRight Only authenticated Admins can access the data. 85 | * @apiError UserNameTooShort Minimum of 5 characters required. 86 | * 87 | * @apiErrorExample Response (example): 88 | * HTTP/1.1 400 Bad Request 89 | * { 90 | * "error": "UserNameTooShort" 91 | * } 92 | */ 93 | 94 | /** 95 | * @api {post} /user Create a new User 96 | * @apiVersion 0.3.0 97 | * @apiName PostUser 98 | * @apiGroup User 99 | * @apiPermission none 100 | * 101 | * @apiDescription In this case "apiErrorStructure" is defined and used. 102 | * Define blocks with params that will be used in several functions, so you dont have to rewrite them. 103 | * 104 | * @apiParam {String} name Name of the User. 105 | * 106 | * @apiSuccess {String} id The new Users-ID. 107 | * 108 | * @apiErrorStructure CreateUser 109 | */ 110 | 111 | /** 112 | * @api {post} /user Create a User 113 | * @apiVersion 0.2.0 114 | * @apiName PostUser 115 | * @apiGroup User 116 | * @apiPermission none 117 | * 118 | * @apiDescription In this case "apiErrorStructure" is defined and used. 119 | * Define blocks with params that will be used in several functions, so you dont have to rewrite them. 120 | * 121 | * @apiParam {String} name Name of the User. 122 | * 123 | * @apiSuccess {String} id The Users-ID. 124 | * 125 | * @apiErrorStructure CreateUser 126 | */ 127 | 128 | /** 129 | * @api {put} /user/:id Change a new User 130 | * @apiVersion 0.3.0 131 | * @apiName PutUser 132 | * @apiGroup User 133 | * @apiPermission none 134 | * 135 | * @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiErrorStructure" 136 | * 137 | * @apiParam {String} name Name of the User. 138 | * 139 | * @apiErrorStructure CreateUser 140 | */ 141 | --------------------------------------------------------------------------------