Writing jsdoc in YAML is very difficult with comments

[dilipkumar2k6]

I liked this module however when I tried to use it for my API then it became nightmare as its very difficult to hand code JSDoc in YAML style. Very tough to write valid YAML syntax inside the comments.

Can I used any other comment format?

[chdanielmueller]

Hi @dilipkumar2k6

What format would you prefer to describe the spec with?
I think to write JSON in JSDoc is not very handy to read and it looks a bit missplaced in the documentation.

I am keen to hear about your opinion on this.

• Daniel

[dilipkumar2k6]

I would prefer to use pure JSDoc if possible. Writing yaml in comments is very difficult. I found following module useful in terms of writing the docs however quality of generated swagger.yaml is not good.
https://github.com/fsbahman/apidoc-swagger

Still not able to make decision to choose the better approach.

[fyodorvi]

@dilipkumar2k6 apidoc-swagger is super buggy, quite useless

If you look at source code you'll see that the guy hardcoded 200 for every response.

[chdanielmueller]

Hi @dilipkumar2k6,

As you said by yourself https://github.com/fsbahman/apidoc-swagger uses another approach in documenting the swagger documentation.
It is not the purpose of this package to support all kinds of documentation styles, but one way in a good working manner.

I hope you can decide on one or the other package.

Regards,
Daniel

[dietergeerts]

The way to write the swagger docs as yaml inside jsdoc is really not useful, it's hard to maintain, hard to read etc.... I would prefer to use something like apidoc-swagger, but better, where you also can use normal jsdoc typedefs as return types etc... as otherwise, you end up documenting everything twice now....

[kalinchernev]

Since 1.9.0 you can use external files to which are included in your specification.

[410063005]

master...410063005:swagger-jsdoc:master

I modified a little in the fork. It works well without the '*'. A late reply to an old issuse.