Core parser library to generate apidoc result following the apidoc-spec.
If you are an end user, please proceed to apidoc or apidoc-documentation.
Core parser library to generate apidoc.json result following the apidoc-spec
License: Other
Core parser library to generate apidoc result following the apidoc-spec.
If you are an end user, please proceed to apidoc or apidoc-documentation.
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?
It would be very beneficial if this lib would be able to generate OpenAPI spec document. (https://www.openapis.org/)
* @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
The parameter fields is out of order for @apiParam and @apiSuccess.
for example:
/**
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.
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.
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)
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\(\)#:\\.\\/\\\\\\[\\]_-]+)'
?
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?
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?
The @apiPrivate parser currently returns a string:
apidoc-core/lib/parsers/api_private.js
Lines 1 to 3 in c32ada3
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
http://apidocjs.com/#param-api-param
For example:
The default value shows up as 0 when generating swagger.json. When generating doc with api-doc, the default shows up as 18.
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
:
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
Hello,
The following file indicated that the delimiters for elixir files are '''
:
apidoc-core/lib/languages/ex.js
Line 8 in 2069f4e
But on the http://apidocjs.com/ website, it seems to indicate that the delimiters are #{
, #
and #}
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
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.
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.
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)?
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 ;)
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.
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
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.
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 _
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.
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.
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
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?
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.
Line 38 in 8ead7e7
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.
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.
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?
The Wrench module has been deprecated. The recommendation from the developer of Wrench is to use fs-extra.
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.
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?
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
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.