Launch Week Day 5: Introducing Reachability for PHP.Learn More →
Socket
Book a DemoSign in
Socket
Book a DemoSign in

apidoc

Package Overview
Dependencies
Maintainers
1
Versions
96
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

apidoc - npm Package Compare versions

Comparing version
0.12.3
 to
0.13.0
.jshintignore

Sorry, the diff of this file is not supported yet

+68
MARKDOWN.md
# Markdown Parser
By default apiDoc uses [markdown-it](https://github.com/markdown-it/markdown-it) Markdown Parser.
If you need to modify the parser options or use an other markdown parser, create a .js file with a custom parser.
Visit the markdown-it page for details, in particular if you want to use markdown plugins.
## Custom Parser
`apidoc --markdown /path/to/a/custom_markdown_parser.js`
Your custom parser must return a class with a render-method.
## Examples
### With "markdown-it" Markdown Parser.
```js
var Markdown = require('markdown-it');
function CustomMarkdownParser() {
this.markdownParser = new Markdown({
breaks : false,
html : true,
linkify : true,
typographer: false
});
}
module.exports = CustomMarkdownParser;
CustomMarkdownParser.prototype.render = function(text) {
return this.markdownParser.render(text);
};
```
### With "marked" Markdown Parser.
**marked seemed to be outdated and has currently a security issue, please use it not anymore in production.**
This is only an demo.
```js
var markdownParser = require('marked');
function CustomMarkdownParser() {
markdownParser.setOptions({
gfm : true,
tables : true,
breaks : false,
pedantic : false,
sanitize : false,
smartLists : false,
smartypants: false
});
}
module.exports = CustomMarkdownParser;
CustomMarkdownParser.prototype.render = function(text) {
return markdownParser(text);
};
```
+25
template/locales/fr.js
define({
fr: {
'Allowed values:' : 'Valeurs autorisées :',
'Compare all with predecessor': 'Tout comparer avec ...',
'compare changes to:' : 'comparer les changements à :',
'compared to' : 'comparer à',
'Default value:' : 'Valeur par défaut :',
'Description' : 'Description',
'Field' : 'Champ',
'General' : 'Général',
'Generated with' : 'Généré avec',
'Name' : 'Nom',
'No response values.' : 'Aucune valeur de réponse.',
'optional' : 'optionel',
'Parameter' : 'Paramètre',
'Permission:' : 'Permission :',
'Response' : 'Réponse',
'Send' : 'Envoyer',
'Send a Sample Request' : 'Envoyer une requête représentative',
'show up to version:' : 'Montrer à partir de la version :',
'Size range:' : 'Ordre de grandeur :',
'Type' : 'Type',
'url' : 'url'
}
});
+25
template/locales/pl.js
define({
pl: {
'Allowed values:' : 'Dozwlone wartości:',
'Compare all with predecessor': 'Porównaj z poprzednimi wersjami',
'compare changes to:' : 'porównaj zmiany do:',
'compared to' : 'porównaj do:',
'Default value:' : 'Wartość domyślna:',
'Description' : 'Opis',
'Field' : 'Pole',
'General' : 'Generalnie',
'Generated with' : 'Wygenerowano z',
'Name' : 'Nazwa',
'No response values.' : 'Brak odpowiedzi.',
'optional' : 'opcjonalny',
'Parameter' : 'Parametr',
'Permission:' : 'Uprawnienia:',
'Response' : 'Odpowiedź',
'Send' : 'Wyślij',
'Send a Sample Request' : 'Wyślij przykładowe żądanie',
'show up to version:' : 'pokaż do wersji:',
'Size range:' : 'Zakres rozmiaru:',
'Type' : 'Typ',
'url' : 'url'
}
});
+25
template/locales/pt_br.js
define({
'pt_br': {
'Allowed values:' : 'Valores permitidos:',
'Compare all with predecessor': 'Compare todos com antecessores',
'compare changes to:' : 'comparar alterações com:',
'compared to' : 'comparado com',
'Default value:' : 'Valor padrão:',
'Description' : 'Descrição',
'Field' : 'Campo',
'General' : 'Geral',
'Generated with' : 'Gerado com',
'Name' : 'Nome',
'No response values.' : 'Sem valores de resposta.',
'optional' : 'opcional',
'Parameter' : 'Parâmetro',
'Permission:' : 'Permissão:',
'Response' : 'Resposta',
'Send' : 'Enviar',
'Send a Sample Request' : 'Enviar um Exemplo de Pedido',
'show up to version:' : 'aparecer para a versão:',
'Size range:' : 'Faixa de tamanho:',
'Type' : 'Tipo',
'url' : 'url'
}
});
+25
template/locales/ru.js
define({
ru: {
'Allowed values:' : 'Допустимые значения:',
'Compare all with predecessor': 'Сравнить всё с предыдущей версией',
'compare changes to:' : 'сравнить с:',
'compared to' : 'в сравнении с',
'Default value:' : 'По умолчанию:',
'Description' : 'Описание',
'Field' : 'Название',
'General' : 'Общая информация',
'Generated with' : 'Сгенерировано с помощью',
'Name' : 'Название',
'No response values.' : 'Нет значений для ответа.',
'optional' : 'необязательный',
'Parameter' : 'Параметры',
'Permission:' : 'Доступ:',
'Response' : 'Ответ',
'Send' : 'Отправить',
'Send a Sample Request' : 'Отправить тестовый запрос',
'show up to version:' : 'показать версию:',
'Size range:' : 'Ограничения:',
'Type' : 'Тип',
'url' : 'url'
}
});
+26
-0
CHANGELOG.md
# apiDoc Changelog
#### 0.13.0
**Important changes**:
* __Remove__ deprecated annotations [http://apidocjs.com/deprecated.html].
* __Replace__ markdown parser (markdown-it)[https://github.com/markdown-it/markdown-it].
* CLI
* Add path to config file (with `-c`).
* Add multiple input locations (with `-i`).
* Remove markdown config parameters, for custom configurations view [MARKDOWN.md].
* Disable warning if packageJson.apidoc was defined.
* Add litcoffee and scala file extension.
* Template
* Add `template.forceLanguage` in `apidoc.json` to set a fixed language file without auto-detect the browser language.
* Add word wrap for pure text examples.
* Add Brazilian, French, Polish and Russian translation files.
* Parser
* Remove deprecated annotations [http://apidocjs.com/deprecated.html].
* Replace markdown parser with (markdown-it)[https://github.com/markdown-it/markdown-it].
* Add custom markdown parser support, view [MARKDOWN.md] for details.
* Add support for markdown in the type section. Example: `@apiParam {(CustomType)[http://...link-to-description.html]}`
#### 0.12.2

@@ -4,0 +30,0 @@ 

+33
-3
CONTRIBUTORS.md

@@ -5,2 +5,32 @@ # apiDoc Contributors

* [Frank Lucht](https://github.com/Digigoodz)
* Add multiple input locations [#239](https://github.com/apidoc/apidoc/pull/239)
* [赵健](https://github.com/karboom)
* Add word wrap for text examples [#241](https://github.com/apidoc/apidoc/pull/241)
* [Tyler Clemens](https://github.com/tielur)
* Add a check to see if packageJson.apidoc was defined [#227](https://github.com/apidoc/apidoc/pull/227)
* [Dmitry Krasyukov](https://github.com/p00h), [Alexej Yaroshevich](https://github.com/zxqfox), [Dmitry Kirilyuk](https://github.com/Jokero)
* Add Russian translation [#237](https://github.com/apidoc/apidoc/pull/237)
* [Bruno Wego](https://github.com/brunowego)
* Add Brazilian translation [#249](https://github.com/apidoc/apidoc/pull/249)
* [Rafał Zielonka](https://github.com/Bombaharris)
* Add Polish translation [#199](https://github.com/apidoc/apidoc/pull/199)
* [Vincent Hérilier](https://github.com/vherilier)
* Add French translation [#191](https://github.com/apidoc/apidoc/pull/191)
* [Hector Hernandez](https://github.com/alfadormx)
* Added support for markdown in the type section [#1](https://github.com/apidoc/apidoc-core/pull/1)
* [Goonoo Kim](https://github.com/mctenshi)
* Added litcoffee file extension [#5](https://github.com/apidoc/apidoc-core/pull/5)
* [Nil Gradisnik](https://github.com/nilgradisnik)
* Added scala file extension [#2](https://github.com/apidoc/apidoc-core/pull/2)
* [Christopher Martin](https://github.com/chris-martin)

@@ -10,9 +40,9 @@ * Unindent strings [#173](https://github.com/apidoc/apidoc/pull/173)

* [大鼻子](https://github.com/wohugb)
* Add chinese translation (missing translations from google).
* Add chinese translation (missing translations from google)
* [kimhoo](https://github.com/kimhoo)
* Add dutch translation (missing translations from google).
* Add dutch translation (missing translations from google)
* [Danny Olson](https://github.com/dbolson)
* Add Clojure parser.
* Add Clojure parser

@@ -19,0 +49,0 @@ * [Eugene Jo](https://github.com/iameugenejo)

+8
-8
example/_apidoc.js

@@ -14,8 +14,8 @@ // ------------------------------------------------------------------------------------------

/**
* @apiDefineErrorStructure CreateUserError
* @apiDefine CreateUserError
* @apiVersion 0.2.0
*
*
* @apiError NoAccessRight Only authenticated Admins can access the data.
* @apiError UserNameTooShort Minimum of 5 characters required.
*
*
* @apiErrorExample Response (example):

@@ -33,3 +33,3 @@ * HTTP/1.1 400 Bad Request

/**
* @apiDefinePermission admin Admin access rights needed.
* @apiDefine admin Admin access rights needed.
* Optionally you can write here further Informations about the permission.

@@ -47,3 +47,3 @@ *

/**
* @apiDefinePermission admin This title is visible in version 0.1.0 and 0.2.0
* @apiDefine admin This title is visible in version 0.1.0 and 0.2.0
* @apiVersion 0.1.0

@@ -97,3 +97,3 @@ */

* Define blocks with params that will be used in several functions, so you dont have to rewrite them.
*
*
* @apiParam {String} name Name of the User.

@@ -103,3 +103,3 @@ *

*
* @apiErrorStructure CreateUserError
*/
* @apiUse CreateUserError
*/
+1
-1
example/apidoc.json

@@ -20,2 +20,2 @@ {

}
}
}
+7
-7
example/example.js

@@ -9,3 +9,3 @@ /**

* @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.
*
*
* @apiParam {Number} id The Users-ID.

@@ -17,3 +17,3 @@ *

* @apiSuccess {Number} id The Users-ID.
* @apiSuccess {Date} registered Registration Date.
* @apiSuccess {Date} registered Registration Date.
* @apiSuccess {Date} name Fullname of the User.

@@ -30,3 +30,3 @@ * @apiSuccess {String[]} nicknames List of Users nicknames (Array of Strings).

* @apiError UserNotFound The <code>id</code> of the User was not found.
*
*
* @apiErrorExample Response (example):

@@ -49,3 +49,3 @@ * HTTP/1.1 401 Not Authenticated

* Define blocks with params that will be used in several functions, so you dont have to rewrite them.
*
*
* @apiParam {String} name Name of the User.

@@ -55,3 +55,3 @@ *

*
* @apiErrorStructure CreateUserError
* @apiUse CreateUserError
*/

@@ -71,4 +71,4 @@ function postUser() { return; }

*
* @apiErrorStructure CreateUserError
* @apiUse CreateUserError
*/
function putUser() { return; }
function putUser() { return; }
+32
-22
lib/index.js
var _ = require('lodash');
var apidoc = require('apidoc-core');
var fs = require('fs-extra');
var markdown = require('marked');
var path = require('path');
var winston = require('winston');
var Markdown = require('markdown-it');

@@ -18,15 +18,5 @@ var PackageInfo = require('./package_info');

simulate: false,
parse : false, // only parse and return the data, no file creation
parse : false, // Only parse and return the data, no file creation.
colorize: true,
markdown: true,
marked: {
gfm : true,
tables : true,
breaks : false,
pedantic : false,
sanitize : false,
smartLists : false,
smartypants: false
}
markdown: true
};

@@ -36,7 +26,7 @@

log : {},
markdown: false,
markdownParser: null,
options : {}
};
// uncaughtException
// Display uncaught Exception.
process.on('uncaughtException', function(err) {

@@ -57,2 +47,3 @@ console.error((new Date()).toUTCString() + ' uncaughtException:', err.message);

var apidocPath = path.join(__dirname, '../');
var markdownParser;
var packageInfo;

@@ -62,10 +53,20 @@

// paths
// Paths.
options.dest = path.join(options.dest, './');
options.template = path.join(options.template, './');
// options
// Line-Ending.
if (options.lineEnding) {
if (options.lineEnding === 'CRLF')
options.lineEnding = '\r\n'; // win32
else if (options.lineEnding === 'CR')
options.lineEnding = '\r'; // darwin
else
options.lineEnding = '\n'; // linux
}
// Options.
app.options = options;
// logger
// Logger.
app.log = new (winston.Logger)({

@@ -83,7 +84,16 @@ transports: [

// markdown
// Markdown Parser: enable / disable / use a custom parser.
if(app.options.markdown === true) {
app.markdown = markdown;
app.markdown.setOptions(app.options.marked);
markdownParser = new Markdown({
breaks : false,
html : true,
linkify : false,
typographer: false
});
} else if(app.options.markdown !== false) {
// Include custom Parser @see MARKDOWN.md and test/fixtures/custom_markdown_parser.js
Markdown = require(app.options.markdown); // Overwrite default Markdown.
markdownParser = new Markdown();
}
app.markdownParser = markdownParser;

@@ -102,3 +112,3 @@ try {

apidoc.setLogger(app.log);
apidoc.setMarkdownParser(app.markdown);
apidoc.setMarkdownParser(markdownParser);
apidoc.setPackageInfos(packageInfo.get());

@@ -105,0 +115,0 @@ 

+33
-9
lib/package_info.js

@@ -47,4 +47,4 @@ var _ = require('lodash');

if (Object.keys(apidocJson).length === 0)
app.log.warn('Please create an apidoc.json.');
if (Object.keys(apidocJson).length === 0 && ! packageJson.apidoc)
app.log.warn('Please create an apidoc.json configuration file.');

@@ -64,11 +64,12 @@ return result;

var result = {};
var jsonFilename = path.join(app.options.src, filename);
var dir = this._resolveSrcPath();
var jsonFilename = path.join(dir, filename);
// read from source dir
// Read from source dir
if ( ! fs.existsSync(jsonFilename)) {
// read vom current dir
jsonFilename = './' + filename;
// Read from config dir (default './')
jsonFilename = path.join(app.options.config, filename);
}
if ( ! fs.existsSync(jsonFilename)) {
app.log.debug(filename + ' not found!');
app.log.debug(jsonFilename + ' not found!');
} else {

@@ -93,6 +94,10 @@ try {

var result = {};
var self = this;
['header', 'footer'].forEach(function(key) {
if (json[key] && json[key].filename) {
var filename = path.join(app.options.src, json[key].filename);
// var filename = path.join(app.options.src, json[key].filename);
var dir = self._resolveSrcPath();
var filename = path.join(dir, json[key].filename);
if ( ! fs.existsSync(filename))

@@ -106,3 +111,3 @@ filename = path.join('./', json[key].filename);

title : json[key].title,
content: app.markdown ? app.markdown(content) : content
content: app.markdownParser ? app.markdownParser.render(content) : content
};

@@ -117,1 +122,20 @@ } catch (e) {

};
/**
* Resolve source path.
*
* If multiple input dirs are given, the current workdir './' will be returned.
* On one input dir, the current workdir will be the input dir.
*
* @returns {string}
* @private
*/
PackageInfo.prototype._resolveSrcPath = function() {
var dir = './';
if (app.options.src instanceof Array && app.options.src.length === 1)
dir = app.options.src[0];
return dir;
};
+1
-1
LICENSE

@@ -1,2 +0,2 @@

Copyright (c) 2013-2014 inveris OHG
Copyright (c) 2013-2015 inveris OHG
Author Peter Rottmann <rottmann@inveris.de>

@@ -3,0 +3,0 @@ Licensed under the MIT license.

+6
-6
package.json
{
"name": "apidoc",
"version": "0.12.3",
"version": "0.13.0",
"description": "RESTful web API Documentation Generator",

@@ -39,6 +39,6 @@ "author": "Peter Rottmann <rottmann@inveris.de>",

"dependencies": {
"apidoc-core": "~0.3.2",
"fs-extra": "~0.18.1",
"lodash": "~3.6.0",
"marked": "~0.3.3",
"apidoc-core": "~0.4.0",
"fs-extra": "~0.18.2",
"lodash": "~3.8.0",
"markdown-it": "^4.2.1",
"nomnom": "~1.8.1",

@@ -53,3 +53,3 @@ "winston": "~1.0.0"

"path-to-regexp": "^1.0.3",
"semver": "^4.3.3",
"semver": "^4.3.4",
"should": "~6.0.1"

@@ -56,0 +56,0 @@ },

+7
-1
README.md

@@ -53,3 +53,3 @@ # apiDoc

* **C#, Go, Dart, Java, JavaScript, PHP** (all DocStyle capable languages):
* **C#, Go, Dart, Java, JavaScript, PHP, Scala** (all DocStyle capable languages):

@@ -133,2 +133,8 @@ ```javascript

## Converter
* [apidoc-swagger](https://github.com/fsbahman/apidoc-swagger)
* [gulp-apidoc-swagger](https://github.com/fsbahman/gulp-apidoc-swagger)
## Help

@@ -135,0 +141,0 @@ 

+4
-0
template/css/style.css

@@ -175,2 +175,6 @@ /* ------------------------------------------------------------------------------------------

code.language-text {
word-wrap: break-word;
}
pre.language-json {

@@ -177,0 +181,0 @@ overflow: auto;

+24
-13
template/locales/locale.js
define([
'./locales/de.js',
'./locales/fr.js',
'./locales/nl.js',
'./locales/pl.js',
'./locales/pt_br.js',
'./locales/ru.js',
'./locales/zh.js'
], function() {
var langId = (navigator.language || navigator.userLanguage).toLowerCase();
var language = langId.substr(0, 2);
var locales = {};
for(index in arguments) {
for(property in arguments[index]) {
for (index in arguments) {
for (property in arguments[index])
locales[property] = arguments[index][property];
}
}
if ( ! locales['en'])
locales['en'] = {};
var language = ((navigator.language) ? navigator.language : navigator.userLanguage).substr(0, 2).toLowerCase();
if( ! locales['en'])
locales['en'] = {};
if( ! locales[language])
if ( ! locales[langId] && ! locales[language])
language = 'en';
var locale = locales[language];
var locale = (locales[langId] ? locales[langId] : locales[language]);
var __ = function(text) {
function __(text) {
var index = locale[text];
if(index === undefined) return text;
if (index === undefined)
return text;
return index;
};
function setLanguage(language) {
locale = locales[language];
}
return {
__ : __,
locales: locales,
locale : locale
__ : __,
locales : locales,
locale : locale,
setLanguage: setLanguage
};
});
+3
-0
template/main.js

@@ -78,2 +78,5 @@ require.config({

if (apiProject.template.forceLanguage)
locale.setLanguage(apiProject.template.forceLanguage);
// Setup jQuery Ajax

@@ -80,0 +83,0 @@ $.ajaxSetup(apiProject.template.jQueryAjaxSetup);

bin/apidoc

Sorry, the diff of this file is not supported yet