Rendering preview for spring-restdocs documentation

[luvarqpp]

Documenting rest api using spring-restdocs in InteliJ Idea is fine, but I missing rendered "include" snippets of operation macro.
Consider reading project dependencies and look at them for extensions used while docs rendering. Mainly I am using spring-restdocs-asciidoctor dependency (it is in maven central).

Example macro which is not getting proper render is operation. See this example:

== Get Comments sorted

To get sorted according single attribute and with no specific ordering (asc-ending is default), you can refer to this example:

operation::comments/getSortedDescending[snippets='http-request,path-parameters,http-response']

For some nice simple example you can have a look on one of sample restdocs project on github.

AsciiDoc Plugin Version: 0.28.26

IDE Name and Version:
IntelliJ IDEA 2019.1.4 (Community Edition)
Build #IC-191.8026.42, built on July 30, 2019
JRE: 1.8.0_212-release-1586-b4 amd64
JVM: OpenJDK 64-Bit Server VM by JetBrains s.r.o
Linux 4.18.0-25-generic

[luvarqpp]

sidenote: I have asked how to make given set-up to work on stackoverflow.
PS: I like your plugin, because it renders plantuml graphs and many more things correctly.

[ahus1]

I've had a look at spring-restdocs-asciidoctor. The operation::[] is an extension that renders the content. It relies on an attribute snippets that needs to be set.

The IntelliJ plugin for AsciiDoc supports both ruby extensions and attributes for previews as experimental options.

To make it work I did the following:

• checkout the project
• running gradlew asciidoctor to generate the snippets
• add a file .asciidoctorconfig to set the path to the generated snippets
• add a directory .asciidoctor and place the extension in this directory
• confirm the warning message "This project contains Asciidoctor Extensions..." in the IDE

You need to confirm the warning message every time you restart your IDE. As it will run Ruby code locally, this is a security issue. Maybe we'll enhance it in the future so you only need to reconfirm it once the extension's code changes.

I modified the extension a bit as it currently throws some warning messages, I'll contribute that to upstream later.

The changes are on the following branch: https://github.com/ahus1/spring-restdocs/tree/poc_extension_intellij

Please give it a try; I suppose it will work for you.

If you think some more documentation on this topic is missing, please suggest where to add it (or create a PR).

[luvarqpp]

Hi @ahus1 ,
thanks for examination, reply, manual and a lot of effort.

First thing, after reading your info I have nearly done it. Than I have look at your commit to sample project and I fixed my set-up. Rendering of operations now works and I have also fixed missing things like project-version attribute and testsourcedir attribute in my project. Also inclusion of sample code from project work now.

Second one, is it possible to generate "lib" folder by plugin, when it sees dependency on spring-restdocs? Would it be appropriate?

Third one, if you would provide some simple answer on my stackoverflow question, I would mark it as solution.

Fourth, according documentation... I have installed your plugin in "standard, random" way. When I have created aaa.adoc file in my project, Idea had asked me if I would like to install plugin to help with given filetype. I have answered "yes" and so it has been installed. I have not seen your documentation wiki, nor anything that would make me curious about "plugin features", or "plugin extensibility/configuration".

I would suggest to display some sort of info in "balloon" when you detect first "fail" when rendering. I mean missing macro, or missing attribute. You can provide at least link to wiki; at most "one click" to create config file with missing attribute value set to some string. It would provide headstart without knowing how to set attribute in asciidoctor format.

Thanks again,
Lubo

[ahus1]

Hello @luvarqpp - thank for sharing your experiences. These features should be more approachable to first time users.

Adding a balloon would be a good idea. We have already balloon to guide the user to the setup of JavaFX.

I'll open some issues for that. I could imaging a balloon for:

• an include that doesn't resolve and is using a variable -> offer to add .asciidoctorconfig file / Help user to setup .asciidoctorconfig for attributes #313
• an operation::[] exists in the document (plus maybe other conditions) -> offer to add a pre-filled lib folder for spring-rest-docs / Support spring-restdocs out of the box #312

If you have additional ideas, please share them as issues or in a personal email.

I've add a abridged version to SO, please feel free to accept it as an answer.

[ahus1]

Update for anyone watching this ticket: spring rest support is now included in the plugin starting from release 0.30.3, no need to fill the .lib folder any more: #312

See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Spring-REST-Docs-support for more details.