> The original problem swagger tries to solve is: API documentation. So, if you need to document an API, use a format that is created for that purpose. I highly recommend using Asciidoctor for writing documentation. There are some tools for Java that help you with this. However they are somehow technology specific. For instance Spring REST Docs works very well if you are using Spring / Spring Boot.
I have used Asciidoctor + Spring REST Doc to document a complex REST API and my experience was almost complete the opposite for a number of reasons.
1.) Asciidoctor is powerful but exceedingly tedious to edit. It's especially painful to use for documenting an API in advance--wikis like Confluence are far easier to use and also allow commenting.
2.) Spring REST Doc generates snippets of asciidoc text that you must laboriously incorporate into the parent asciidoc. It's particular painful when combined with maven (another source of pain for some of us). Anybody who has asked the question "where do I look in target to find my output?" as well as "now that I found the output how do I make it go somewhere else instead?" knows what I mean.
3.) The unit tests that Spring REST Doc depends on to generate output are hard to maintain for anything beyond trivial cases. I've spent countless hours debugging obscure bugs caused by Spring IoC problems. Also, the DSL format used to define output of examples is hard to understand--just getting URLs to show https schemes and paths takes time.
Finally, I would disagree that Swagger is purely designed to document existing REST interfaces. We're using it to design the interfaces in advance. It's not perfect but works better than other tools I have found let alone informal specification via a wiki. Spring REST Doc is close to useless for design.
I have used Asciidoctor + Spring REST Doc to document a complex REST API and my experience was almost complete the opposite for a number of reasons.
1.) Asciidoctor is powerful but exceedingly tedious to edit. It's especially painful to use for documenting an API in advance--wikis like Confluence are far easier to use and also allow commenting.
2.) Spring REST Doc generates snippets of asciidoc text that you must laboriously incorporate into the parent asciidoc. It's particular painful when combined with maven (another source of pain for some of us). Anybody who has asked the question "where do I look in target to find my output?" as well as "now that I found the output how do I make it go somewhere else instead?" knows what I mean.
3.) The unit tests that Spring REST Doc depends on to generate output are hard to maintain for anything beyond trivial cases. I've spent countless hours debugging obscure bugs caused by Spring IoC problems. Also, the DSL format used to define output of examples is hard to understand--just getting URLs to show https schemes and paths takes time.
Finally, I would disagree that Swagger is purely designed to document existing REST interfaces. We're using it to design the interfaces in advance. It's not perfect but works better than other tools I have found let alone informal specification via a wiki. Spring REST Doc is close to useless for design.