apidoc/apidoc-core

Core parser library to generate apidoc.json result following the apidoc-spec

apidoc-core

ARCHIVED: this repository has been archived because it is now part of the apidoc main repository

Core parser library to generate apidoc result following the apidoc-spec.

If you are an end user, please proceed to apidoc or apidoc-documentation.

apidoc-core's Issues

Unable to use a @ in parameter names

   * @apiParam (Request Fields) {String} @version Record version

somehow gets compiled without errors, but the whole result is broken (nothing displayed but sidebar, title and "Generated with ...")

Any chance to escape it?

TIA

Wrench is deprecated

The Wrench module has been deprecated. The recommendation from the developer of Wrench is to use fs-extra.

include filename in warning

currently is says:
warn: parser plugin 'param' not found in block: 34

would be a bit nicer if it said:
warn: parser plugin 'param' not found in block: 34 in file Controller\StatisticsController.php

Wrench package is deprecated

npm WARN deprecated [email protected]: wrench.js is deprecated!
You should check out fs-extra (https://github.com/jprichardson/node-fs-extra)
for any operations you were using wrench for.
Thanks for all the usage over the years.

Trying to get in touch regarding a security issue

Hi there,

I couldn't find a SECURITY.md in your repository and am not sure how to best contact you privately to disclose a security issue.

Can you add a SECURITY.md file with an e-mail to your repository, so that our system can send you the vulnerability details? GitHub suggests that a security policy is the best way to make sure security issues are responsibly disclosed.

Once you've done that, you should receive an e-mail within the next hour with more info.

Thanks! (cc @huntr-helper)

Add a literal escape tag

Instead of allowing special characters in some fields and not others add a literal escape so users can output : or [ in fields. See http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#%7B@literal%7D

Use case:
I want to set the fieldname of my GET parameter to aaab[ccdd] but the parser only recognises alphanumeric, slash etc. Allow me to manually escape the [ and ] characters.

Error in the documentation about erlang parser

Hello,

The following file indicated that the delimiters for elixir files are ''' :

apidoc-core/lib/languages/ex.js

Line 8 in 2069f4e

docBlocksRegExp: /@apidoc\s*(~[sS])?"""\uffff?(.+?)\uffff?(?:\s*)?"""|@apidoc\s*(~[sS])?'''\uffff?(.+?)\uffff?(?:\s*)?'''/g,

But on the http://apidocjs.com/ website, it seems to indicate that the delimiters are #{, # and #}

Apidoc special comment closing symbols.

Hi,

I've a problem and trust some of you can help me solve. I need to mix code and documentation in order to make my life easier. I'll explain further if needed but in few words what I need is something like php does when you mix it with html.

/**
 * @api {js} users Schema
 * @apiName Schema
 * @apiGroup User
 * @apiExample {js} Entity schema:
 <*/   // "fake" bracket closing. if I use the <*/ closing apidoc continues reading as if I haven't closed the comment
{
   [json pseuschema]
}
/* */ // real apidoc "segment" closing

The effect should be that the uncommented section is still considered part of the apidoc even if it is not comment, so I can include my schema without copy pasting. There might be some straightforward ways to do so, but I've found none.

What I've done though has been to overwrite the default language (I use Javascript) with the parameter --parse-languages default=custom.js, defining new regular expression. I have failed to come up with regular expression that might work in my case. My current custom.js file looks like this:

module.exports = {
  // here i try to do not match */ if preceded by <
  docBlocksRegExp: /\/\*\*\uffff?(.+?)\uffff?(?:\s*)?(\*\/)(?!<)/g,
  // remove not needed ' * ', '<*/',  '/*' (for reopening comment sections) and  tabs at the beginning. I don't know if it works
  inlineRegExp: /^(\s*)?(\*|(\/\*>))[ ]?/gm
}

Has any of you had my same need? What solution did you came up with? Do you have some suggestion for my regex (I'm very bad at it)?

OpenAPI support

I found thread #60
Have tried https://www.npmjs.com/package/@forfuture/apidoc-openapi & https://www.npmjs.com/package/apidoc-swagger
However, apidoc-swagger mixed up parameters and responses & no grouping available in apidoc-openapi
Is there any suggestions to convert it to openAPI?

Unable to use a dot in parameter names

I would like to use a dot in a parameter.

This is working:

@apiParam (Query) {String} [filter] Filter on all fields

Array notation is also working:

@apiParam (Query) {String} [filter[username]] Filter username

Using a dot is not working:

@apiParam (Query) {String} [filter[profile.name]] Filter surname on profile

I know the dot is reserved for grouping field names, however this should not be necessary at the array notation like in this example. It would be helpful to have an escape character (backslash) like:

@apiParam (Query) {String} [filter[profile\.name]] Filter surname on profile

Is this possible? Example URL for this use-case:

.../user?filter[profile.name]=John

Add @apiQuery and @apiBody

Hey,
me and a workmate found this project by looking for some API Documentation tools.
When we used it some ideas came up. Apidoc makes no different between an URL param, query or a body param. I know all are params but it would be nice if there is more difference between those three.

Maybe I find some time to create a pull request in a couple of days.

Keep up the nice work ;)

Extend an existing parser

Hello. I am trying to extend the @apiSuccessExample annotation to add some options like loading the response body from an external json file. I have created a new Hook that calls my custom parser function. The problem is that the original parser is not called anymore, so the original logic is not working anymore. I thought of "copy" the original code to my function but it has some dependencies on apidoc core libraries.

Any ideas?

Hooks are synchronous, but plugins depend on asynchronous code

Problem

I'm working on a project that's currently using apidoc in conjunction with apidoc-plugin-schema (as recommended by the apidoc readme). This works for older versions.

However, I'm working on upgrading a project to node 12. This involves updating several dependencies to newer versions, including json-schema-ref-parser, which is a dependency of apidoc-plugin-schema. The version of json-schema-ref-parser that's compatible with node 12 also now uses async/await instead of callback functions. Because of this, the logic currently built into apidoc-plugin-schema to wait for that callback to function no longer works, and we end up in an infinite loop waiting for something to process that's not being given an opportunity to process.

As far as I know, there's not a way for synchronous code to say "wait for this promise to function before returning". As such, there's not a way to use this plugin in node 12 and/or with the latest version of json-schema-ref-parser.

Suggested Solution

My suggestion is to have calls to applyHook be asynchronous, using await when calling app.hooks[name].func.apply(...). This would allow plugins to run asynchronous code while still returning a value after that async logic has completed.

Field out of order for object parameter

The parameter fields is out of order for @apiParam and @apiSuccess.

for example:

/**

• @api { POST } /member/register/email Register by email
• @apiSampleRequest off
• @apiName io.exchange.member.controller.RegisterController.emailRegister
• @APIGroup Group5
• @apiHeader {String} Content-Type application/json
• @apiParam { String { ^\w+((-\w+)|(.\w+))@[A-Za-z0-9]+((.|-)[A-Za-z0-9]+).[A-Za-z0-9]+$ } } email The email address
• @apiParam { String { 6..6 } } verification_code The verification code
• @apiParam { String } [ country ] The country
• @apiParam { String } [ timezone ] The timezone
• @apiParam { String { ^(?=.[0-9])(?=.[a-z])(?=.*[A-Z]).{8,20}$ } } password The password
• @apiParam { String } [ identify ] Identify
• @apiParam { String } [ invitation_code ] Invitation code
• @apiParam { String } [ lucky_draw_id ]
• @apiParam { String = H5(H5) , WEB(Web) , NATIVE(Native) , UNKNOWN(Unknown) } [ client_type ] Client type
• @apiParam { String } [ geetest_user ] Geetest user
• @apiParam { String } [ geetest_challenge ] Geetest challenge
• @apiParam { String } [ geetest_validate ] Geetest validate
• @apiParam { String } [ geetest_seccode ] Geetest seccode
• @apiSuccess { Long } id The member id
• @apiSuccess { String } token The token of session
• @apiSuccess { String } account account
• @apiSuccess { String = NORMAL , VIP } type Member type
• @apiSuccess { Object } profile The member profile
• @apiSuccess { String } profile.avatar The avatar of member
• @apiSuccess { Object } setting The member setting
• @apiSuccess { String } setting.language The custom language
• @apiSuccess { Object } setting.currency The custom currency
• @apiSuccess { String } setting.currency.name Currency name
• @apiSuccess { String } setting.currency.icon Currency icon
• @apiSuccess { String } timezone timezone
• @apiSuccess { String } country country
• @apiSuccessExample Response
• {"id":1, "token":"", "account":"", "type":"NORMAL", "profile":{"avatar":""}, "setting":{"language":"", "currency":{"name":"", "icon":""}}, "timezone":"", "country":""}
  */

Order of elements should be preserved when using @apiUse

I often combine explicitly defined parameters (@apiParam) and return values (@apiSuccess) with those that come from a template (@apiUse). When doing so, it would be nice if the order of elements was preserved. However, what happens is that all elements included using @apiUse end up last. Here's an example:

/**
 * @apiDefine bar
 * @apiParam {String} bar bar
 */

/**
 * ...
 * @apiParam {String} foo foo
 * @apiUse bar
 * @apiParam {String} baz baz
 */

The expected result is params listed in the following order: foo, bar, baz. Unfortunately, that's not what happens as this screenshot illustrates:

Looking at the code this seems pretty difficult to implement due to the way @apiUse is currently implemented. Any thoughts?

FR: OpenAPI support?

It would be very beneficial if this lib would be able to generate OpenAPI spec document. (https://www.openapis.org/)

@apiUse inside other blocks

I apologize for the slightly ambiguous title, but let me explain what I'm after. I'd basically like to use @apiDefine to define blocks of JSON for different models inside my API, and then @apiUse them inside @apiSuccessExample blocks, so I don't have to repeat them multiple times but can still change things like the response code, or place those objects inside arrays, etc.. For example, this is what I'd imagine:

###
@apiDefine ModelJSON
{
  "hey": "you",
  "look": "here"
}
###

###
@apiSuccessExample {json} Success
  HTTP/1.1 200 OK
  [
    @apiUse ModelJSON,
    @apiUse ModelJSON
  ]
###
getAll: (req, res) ->
  res.send('hey')

###
@apiSuccessExample {json} Success
  HTTP/1.1 200 OK
  @apiUse ModelJSON
###
getOne: (req, res) ->
  res.send('hey')

###
@apiSuccessExample {json} Success
  HTTP/1.1 201 OK
  @apiUse ModelJSON
###
post: (req, res) ->
  res.send('you')

Is there a way to currently do this? or would this require creating a new tag in order to support?

Problems with apiPrivate and Empty parser result.

I think this happens after #71 got merged

I have the following php file called test.php:

<?php

	/**
	 * @apiDescription xxxx.
	 * @api {post} /xxxxx/v1/xxxx.json XXXX
	 * @apiSampleRequest https://xxxxx.com
	 * @apiGroup xxxxx
	 * @apiPrivate
	 * @apiDeprecated use now (xxxxx).
	 */

Now I run

apidoc --color --verbose --private --input . --file-filters ".php"

The output is:

{"message":"Please create an apidoc.json configuration file.","level":"warn"}
{"message":"apidoc-generator name: apidoc","level":"verbose"}
{"message":"apidoc-generator version: 0.19.1","level":"verbose"}
{"message":"apidoc-core version: 0.11.0","level":"verbose"}
{"message":"apidoc-spec version: 0.3.0","level":"verbose"}
{"message":"run parser","level":"verbose"}
{"message":{"description":"xxxx."},"level":"verbose"}
{"message":{"type":"post","url":"/xxxxx/v1/xxxx.json","title":"XXXX"},"level":"verbose"}
{"message":{"url":"https://xxxxx.com"},"level":"verbose"}
{"message":{"group":"xxxxx"},"level":"verbose"}
{"message":"","level":"verbose"}
{"File":"test.php","Block":1,"Element":"@apiPrivate","Source":"@apiPrivate","level":"error","message":"Empty parser result."}

I think this happens after #71 got merged

2 chars missing in all filenames

Hi everyone,

After update when i try to run apidoc on my project i get following error:

error: ENOENT: no such file or directory, open 'C:\Users\Alisinabh\Source\Repos\MyProject\iDocDefs.cs'

I also found out every file or folder starting with 'A' will have same issue. The 'A' and its next char will be ignored.

Im using Node v4.4.4 on windows 10

ApiDoc version: 0.17.3 (problem seems to be in >= 0.17)

Thank you

UPDATE: the problem was in ./utils/find_file.js: Line 145. I will post a pull request with fix.

logger is undefined

apidoc-core/lib/index.js

Line 38 in 8ead7e7

log : logger,

Little improvement of @apiGroup request

Hi!
During parsing @APIGroup, all non-latin symbols treating as 'special chars' and replacing with '_'. It is a bug, which obstacle.

Please, replace regular expression '/[^\w]/g' with '/[.*+?^${}()|[]\]/g' in 'apidoc-core/lib/workers/api_group.js' in function 'postProcess', line 83.

Big thanks, sorry for my English.

Delete route seems not working

When type a doc like @api {delete} /product Removes a product from database the documentation ends up without that route. I saw that already exists a css class named #type__delete on apidoc project, but I think apidoc is not parsing when api has delete type.

WARN deprecated [email protected]: wrench.js is deprecated!

I'm trying to install apidoc npm module, but:

npm WARN deprecated [email protected]: wrench.js is deprecated! You should check out fs-extra (https://github.com/jprichardson/node-fs-extra) for any operations you were using wrench for. Thanks for all the usage over the years.

Remove HTML tags from generated JSON

I noticed that in the generated JSON output, there are p tags in sections like description and type, etc. Example:

{
    "type": "get",
    "url": "/assembly/definition/:did/workspace/:wid/element/:eid",
    "title": "Assembly Definition",
    "name": "GetAssemblyDefinition",
    "description": "<p>Get definition of requested assembly</p> ",
    "group": "Model",
    "version": "0.1.0",
    "permission": [
      {
        "name": "auth",
        "title": "Authenticated access only",
        "description": "<p>Must be logged in to access this resource.</p> "
      }
    ]
}

These are simple to get rid of on the front end that I'm feeding the JSON to, but I think it'd be best to not have them be there in the first place, to separate data from markup. Thoughts?

@group Can not recognize Chinese characters

i found in [apidoc-core/blob/master/lib/workers/api_group.js]

group = group.replace(/[^\w]/g, '_');

when Chinese characters in use ，the content replace by _

@apiPrivate Parser?

Any idea how or where to implement? I can help to do that but I'm a quite lost in this project, any direction would be great.

Unicode line break in the list of allowed types

I am using a rather long list of allowed types. For better readability I break the line. As a result, the \uffff character makes it to the value that follows the line break.

Here's an example:

 * @apiParam {String=alpha,bravo,charlie,delta,echo,foxtrot,golf,hotel,india,juliet,kilo,
 * mike,november,oscar,para,romeo,sierra,tango,uniform,victor,whiskey,xray} letter
 * Phonetic alphabet letter. This is not a real example. I do however came accross a
 * similarly long list of allowed types!

Notice mike being prefixed with \uffff:

Support the runtime doc generation

background:

hi, i want add some decorator in typescript for generating api document in runtime(not in build time). I think it's reasonable for us.

i found that the api-core has the parseSource API, but it's difference with the parse API.
i just need response the https://apidocjs.com/example/api_data.js?v=1628993287127 and the https://apidocjs.com/example/api_project.js?v=1628993287127 which is from the parseSource just like the apidoc cli does.

is that possible?

thanks.

Parser in the browser?

I'd like to be able to use apidoc parser in a browser, however I cannot because it requires the fs module.

It would be nice if the calls to fs.readFileSync could be refactored out of the parser? I want to use apidoc dynamically in the client for lazily generated documentation.

Is this feasible?

@apiDrepricated

It would be nice if there would be an additional Tag '@apiDepricated'.

Now you can show with the compare versions functionality, what has been changed in the past but with this @apiDepricated you could show 'this function will be removed in the future' which will be really nice to inform developers about that some versions before removing it.

building list of files to parse fails on invalid symlink

if there is invalid symlink in path used to find files to parse apidoc fails with error:

ENOENT, no such file or directory '.git/shallow'
debug: Error: ENOENT, no such file or directory '.git/shallow'
at Object.fs.statSync (fs.js:693:18)
at /home/gluedig/source/grinn/nubo/tools/apidoc/node_modules/apidoc-core/lib/utils/find_files.js:81:10
at Array.filter (native)
at FindFiles.search (/home/gluedig/source/grinn/nubo/tools/apidoc/node_modules/apidoc-core/lib/utils/find_files.js:77:23)
at Parser.parseFiles (/home/gluedig/source/grinn/nubo/tools/apidoc/node_modules/apidoc-core/lib/parser.js:80:27)
at Object.parse (/home/gluedig/source/grinn/nubo/tools/apidoc/node_modules/apidoc-core/lib/index.js:200:20)
at Object.createDoc (/home/gluedig/source/grinn/nubo/tools/apidoc/lib/index.js:111:22)
at Object. (/home/gluedig/source/grinn/nubo/tools/apidoc/bin/apidoc:107:12)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)

adding a try/catch around line 81 in lib/utils/find_files.js helps

@apiPrivate parser returns string, causing strange data in output.

The @apiPrivate parser currently returns a string:

apidoc-core/lib/parsers/api_private.js

Lines 1 to 3 in c32ada3

	function parse() {
	return 'private';
	}

When documentation is generated with the --private flag, this results in the following JS/JSON data in the entry:

{
    ...,
    "0": "p",
    "1": "r",
    "2": "i",
    "3": "v",
    "4": "a",
    "5": "t",
    "6": "e",
    ...,
}

Looking at other similar parsers, it seems that the correct output of the parse() function should be an object, like this:

apidoc-core/lib/parsers/api_deprecated.js

Lines 15 to 17 in 2069f4e

	return {
	deprecated: true
	};

Error: Object /path/to/my/file.php has no method 'startsWith'

Hello,

I am a first time user of apidocjs and have been unable to get the command to work. It appears that in apidoc-core/lib/utils/find_files.js it is calling a method that is not defined.

Change default language checker

Feature request

Hi, I want to use apidoc to generate api for my project, which is based on playframework ( scala's web framework). According to its spec, we should write external APIs in a file named route, which is non-file-extension file. But its grammar for comment is not java-like. It can only use one-line comment by #, such as
#this is comment
So I cannot use apidoc for that, I think maybe we can change default language checker, maybe I can change to use Elixir-style comment for apidoc, such as

# {
# this is comment
# }

Thank you

Nullable param types using char "?"

Give the possibility of specifying a nullable parameter with this notation, as with PHP 7.1 :

@apiParam {?MyType} myParameter ...

Therefore replace the type: regex in parsers/api_params.js by : '(\\?[a-zA-Z0-9\(\)#:\\.\\/\\\\\\[\\]_-]+)' ?

Default values from @apiParam ignored.

http://apidocjs.com/#param-api-param

For example:

• @apiParam {Number} [age=18] Optional Age with default 18.

The default value shows up as 0 when generating swagger.json. When generating doc with api-doc, the default shows up as 18.

@apiPrivate not working

When using the @apiPrivate option on a block, I get the following error:
{"message":"parser plugin 'apiprivate' not found in block: 8","level":"warn"}

Switching to @apiIgnore works.