Sample for multi-module setup

ScaCap / spring-auto-restdocs

Spring Auto REST Docs is an extension to Spring REST Docs

https://scacap.github.io/spring-auto-restdocs/

Apache License 2.0

311 stars 86 forks source link

Sample for multi-module setup #278

Closed sebastientromp closed 6 years ago

sebastientromp commented 6 years ago

Hello,

Looking at the doc, it states that a multi-module setup is supported (basically, I have a Controller in 2 different modules, and I want to build a doc that merges all the doc from both modules). I had a look on the web, but could not find any sample for such a setup. Sprint-restdocs rejected a similar issue stating that it was out of scope of the project.

Are you aware of a multi-module project sample that would build a single doc, merging all modules? Is this something you could consider putting together?

Thanks for your help!

jmisur commented 6 years ago

Hi @sebastientromp, multi-module setup scope for SARD is that it supports analysis of classes and json doclet files from other jars (maven modules). You can see the sample projects which all use shared module.

For your case, where you want to put snippets or docs together from multiple modules, that's nothing SARD can help you with. You need to setup your build process so that it copies all generated-javadoc-json and generated-snippets into a single folder (or some "docs" module), so that you can trigger final html generation in there. You should be able to orchestrate that using standard maven modules.

sebastientromp commented 6 years ago

Got it, thanks for the quick reply!

sebastientromp commented 6 years ago

I got something working - not perfect, but good enough.

If you're interested in having a pointer for the doc somewhere I could setup a minimal project, otherwise feel free to close the issue :)

jmisur commented 6 years ago

Great! It would be sufficient if you provide some snippets necessary to configure it, so we have small reference here. Then we can close this.

sebastientromp commented 6 years ago

In the end I did a small sample project :) https://github.com/Travelaer/sard-multi-module-sample

The gist of it is (please keep in mind that's it's just a PoC to get things work, and should be cleaned / improved):

Each module is able to build its own independent doc
It also uses a placeholder attribute to hold the location of snippets (tager/generated-snippets in standalone mode, and . when aggregating everything together)
During pre-package phase, it copies the generated-javadoc-json and generated-snippets to a doc module source directory (that is cleaned in the very beginning of an mvn clean command at project level)
The doc at application level just references the files that are in the source directory

So it's a bit artisanal, but it works :)

jmisur commented 6 years ago

Perfect, thank you. If it works, it's the solution.