How to generate this Spring-boot API documentation example? - spring-boot

I'm trying to track down how some Java Spring-boot API was generated by a developer who has since left the company. The document looks like this:
We have swagger, but this doesn't look like anything generated from that. Definitely doesn't look like javadoc. Any ideas?
Thanks to the answer by João Dias, I found this in pom.xml:
<!-- Run the generated asciidoc through Asciidoctor to generate other
documentation types, such as PDFs or HTML5 -->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<!-- Include Asciidoctor PDF for pdf generation -->
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>1.7.21</version>
</dependency>
</dependencies>
<!-- Configure generic document generation settings -->
<configuration>
<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${generated.asciidoc.directory}</generated>
</attributes>
</configuration>
<!-- Since each execution can only handle one backend, run separate executions
for each desired output type -->
<executions>
<execution>
<id>output-html</id>
<phase>test</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
<pluginManagement>

If I am not mistaken this is Spring REST Docs. For more details:
https://docs.spring.io/spring-restdocs/docs/current/reference/html5/
https://www.baeldung.com/spring-rest-docs

Related

Cucumber rhtml eport is not generating in valid format in selenium cucumber

I'm trying to generate my reports in html format in maven cucumber html report. I'm able to generate cucumber json and cucumber pretty html report, but the issue is the generated report is not in an html format and it doesn't have any data. Can somebody please help me to solve this issue.
Maven pom dependency and plugin
<dependency>
<groupId>com.aventstack</groupId>
<artifactId>extentreports</artifactId>
<version>4.1.5</version>
</dependency>
<!-- https://mvnrepository.com/artifact/net.masterthought/cucumber-reporting -->
<dependency>
<groupId>net.masterthought</groupId>
<artifactId>cucumber-reporting</artifactId>
<version>5.3.0</version>
</dependency>
<plugin>
<groupId>net.masterthought</groupId>
<artifactId>maven-cucumber-reporting</artifactId>
<version>5.1.1</version>
<executions>
<execution>
<id>execution</id>
<phase>verify</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<projectName>CucumberReport</projectName>
<outputDirectory>${project.build.directory}/site/cucumber-reports</outputDirectory>
<!-- <cucumberOutput>${project.build.directory}/cucumber.json</cucumberOutput> -->
<cucumberOutput>${project.build.directory}/cucumber.json</cucumberOutput>
<!-- <parallelTesting>false</parallelTesting> -->
<buildNumber>1</buildNumber>
<checkBuildResult>false</checkBuildResult>
</configuration>
</execution>
</executions>
</plugin>
TestRunner Class
#CucumberOptions(features="testFeature",glue= {"stepDefinitions"}
,plugin={"html:target/site/cucumber-pretty","json:target/cucumber.json"},monochrome=true)
public class TestRunnerTestNG extends AbstractTestNGCucumberTests{
generated report file format
i have found my answer here
https://www.youtube.com/watch?v=PtEp5r6ilKE
and update pom plugin like here not dependency
https://github.com/damianszczepanik/maven-cucumber-reporting
hope it help to others.

Integrate JQAssistant-Maven-Plugin with database analysis via RDBMS Plugin

I´m trying to move my existing software-analysis with jQAssistant (which is basically all steps and scripts in a textfile and executed manually) to the maven-plugin of jQAssistant in order to be able to perform the software-analysis at the build-server.
One step of the analysis is to get information about the database schema. This is done with the RDBMS-Plugin of jQAssistant.
But when i try to perform the analysis with maven the information about the database-connection seems to be lost and no database-analysis is performed at all.
The current code of the plugin-configuration looks like this:
<plugin>
<groupId>com.buschmais.jqassistant</groupId>
<artifactId>jqassistant-maven-plugin</artifactId>
<version>1.8.0</version>
<executions>
<execution>
<id>cli-default</id>
<goals>
<goal>scan</goal>
<goal>analyze</goal>
</goals>
<configuration>
<!-- Scan -->
<scanIncludes>
<scanInclude>
<url>jdbc:oracle:thin:username/password#host:1521:sid</url>
<scope>rdbms:connection</scope>
</scanInclude>
</scanIncludes>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.oracle</groupId>
<artifactId>ojdbc8</artifactId>
<version>12.2.0.1.0</version>
</dependency>
</dependencies>
</plugin>
I couldn´t find anything in the documentation. Is this a limitation of the jqassistant-maven-plugin or is this a configuration error?

cucumber-jvm-parallel-plugin error with glue parameter

I'm trying to use the cucumber-parallel-plugin for the first time.
When I try to run the generateRunners goal I always get an error that my glue-Parameter is missing or have an error...
By the way I try to use this plugin with kotlin.
Here are some relevant pom-snippets:
<build>
<testSourceDirectory>src/test/kotlin</testSourceDirectory>
<plugins>
<plugin>
<groupId>com.github.temyers</groupId>
<artifactId>cucumber-jvm-parallel-plugin</artifactId>
<version>5.0.0</version>
<executions>
<execution>
<id>generateRunners</id>
<phase>generate-test-sources</phase>
<goals>
<goal>generateRunners</goal>
</goals>
<configuration>
<!-- Mandatory -->
<!-- List of package names to scan for glue code. -->
<glue>
<package>cucumber.runtime.step_definitions</package>
</glue>
<outputDirectory>${project.build.directory}/generated-test-sources/cucumber</outputDirectory>
<!-- The directory, which must be in the root of the runtime classpath, containing your feature files. -->
<featuresDirectory>src/test/resources/features</featuresDirectory>
<!-- Directory where the cucumber report files shall be written -->
<cucumberOutputDir>target/cucumber-parallel</cucumberOutputDir>
<plugins>
<plugin>
<name>json</name>
</plugin>
<plugin>
<name>com.example.CustomHtmlFormatter</name>
<extension>html</extension>
</plugin>
</plugins>
<!-- CucumberOptions.strict property -->
<strict>true</strict>
<!-- CucumberOptions.monochrome property -->
<monochrome>true</monochrome>
<!-- The tags to run, maps to CucumberOptions.tags property. Default is no tags. -->
<tags>
<!--tag>~#ignore</tag -->
</tags>
<!-- The naming scheme to use for the generated test classes. One of ['simple', 'feature-title', 'pattern'] -->
<namingScheme>simple</namingScheme>
<!-- The class naming pattern to use. Only required/used if naming scheme is 'pattern'.-->
<namingPattern>Parallel{c}IT</namingPattern>
<!-- One of [SCENARIO, FEATURE]. SCENARIO generates one runner per scenario. FEATURE generates a runner per feature. -->
<parallelScheme>SCENARIO</parallelScheme>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.19</version>
<configuration>
<forkCount>10</forkCount>
<reuseForks>true</reuseForks>
<includes>
<include>**/Parallel*IT.class</include>
</includes>
</configuration>
</plugin>
</plugins>
This console-out I got:
Failed to execute goal com.github.temyers:cucumber-jvm-parallel-plugin:5.0.0:generateRunners (default-cli) on project at.wrkwks.portal-template-webtests: Invalid parameter. Invalid parameter.
[ERROR] The parameters 'glue' are missing or invalid
solution is to use another dependecy for that :-)
<dependency>
<groupId>com.trivago.rta</groupId>
<artifactId>cucable-plugin</artifactId>
<version>${cucable-plugin.version}</version>
</dependency>

How can I compile and run my Custom Doclet class in my project?

I'm trying to dump all class javadoc comment (preferabbly subclasses of a libraries WebPage class) at compile time into a .properties file in the format classname=comment.
So far I have:
created doclet class SiteMapDoclet
the class is defined to scan all the javadocs in the project and dump them to a .properties file
Added the necessary configs to my pom.xml for it to work.
Versions: Java 1.6.0.21, Maven 2.2.1
Problem:
mvn site returns:
Embedded error: Error rendering Maven report:
Exit code: 1 - java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory
at us.ak.state.revenue.cssd.Personnel.utils.SiteMapDoclet.<clinit>(SiteMapDoclet.java:27)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
I tried setting the jars as AdditionalDependencies even though they are normal dependencies for my project.
I also tried adding the paths to the jars I expect my class to need as part of the bootclasspath.
the reporting section of my pom.xml looks like this:
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<reportSets>
<reportSet>
<id>html</id>
<reports>
<report>javadoc</report>
</reports>
</reportSet>
<reportSet>
<id>siteMap</id>
<configuration>
<doclet>
us.ak.state.revenue.cssd.Personnel.utils.SiteMapDoclet
</doclet>
<docletPath>${project.build.outputDirectory}</docletPath>
<destDir>SiteMap</destDir>
<author>false</author>
<useStandardDocletOptions>false</useStandardDocletOptions>
<!-- there has got to be a better way to do this! -->
<!-- how can I fix the CSSD-Web - Base to use a proper manifest file? -->
<bootclasspath>
${bootClassPath};
${env.CLASSPATH};
${m2Repository}/commons-logging/commons-logging/1.1.1/commons-logging-1.1.1.jar;
${m2Repository}/org/apache/wicket/wicket-core/${wicket.version}/wicket-core-${wicket.version}.jar;
${m2Repository}/us/ak/state/revenue/cssd/CSSD-Web/${CSSDWebBase.version}/CSSD-Web-${CSSDWebBase.version}.jar
</bootclasspath>
<additionalDependencies>
<additionalDependency>
<groupId>us.ak.state.revenue.cssd</groupId>
<artifactId>CSSD-Web</artifactId>
<version>${CSSDWebBase.version}</version>
</additionalDependency>
<additionalDependency>
<groupId>org.apache.wicket</groupId>
<artifactId>wicket-core</artifactId>
<version>${wicket.version}</version>
</additionalDependency>
<additionalDependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.16</version>
</additionalDependency>
<additionalDependency>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
<version>1.1.1</version>
</additionalDependency>
</additionalDependencies>
<name>SiteMapDoclet</name>
<description>Page Descriptions for SiteMap generation</description>
</configuration>
<reports>
<report>javadoc</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
NOTE:
${m2Repository} is defined as a property higher up the file,
defined as ${env.USERPROFILE}/.m2/repository
${bootClassPath} is defined as a property higher up the file,
defined as ${env.JRE_6_HOME}\lib\rt.jar;${env.JAVA_HOME}\lib\tools.jar;
How can i fix the NoClassDefFoundError?
Additionally I would like my SiteMap file to run as a part of the normal build process,
after compile but before package.
I've tried defining this in build, but the javadoc doesn't get created and I don't see any logging output from my Doclet.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>build-siteMap-Descriptions</id>
<phase>process-classes</phase>
</execution>
</executions>
</plugin>
UPDATE:
Thanks to #ben75 's suggestion. I've removed the <reporting> section of my pom.xml and now have the process failing during build. I added <goals> and copied the <configuration> section from <reporting>.
It's still throwing the NoClassDefFoundError but it's happening on build where I want it to. I tried adding:
<includeDependencySources>true</includeDependencySources>
<dependencySourceIncludes>
<dependencySourceInclude>org.apache.wicket:wicket-core:*</dependencySourceInclude>
<dependencySourceInclude>org.apache.commons.logging:*</dependencySourceInclude>
<dependencySourceInclude>us.ak.state.revenue.cssd:CSSD-Web:*</dependencySourceInclude>
</dependencySourceIncludes>
To the configuration section, but that didn't work.
You can try to put your <additionalDependencies> as plugin dependendencies:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<dependencies>
<dependency>
<groupId>us.ak.state.revenue.cssd</groupId>
<artifactId>CSSD-Web</artifactId>
<version>${CSSDWebBase.version}</version>
</dependency>
...
To attach javadoc plugin to your normal build process, I think you just need to specify the goal and preferably attaching it to prepare-package phase (so that javadoc is not generated when you simply run the test phase):
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>attach-javadoc</id>
<phase>prepare-package</phase>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Building upon #ben75s Excellent Advice I was able to get it to finally run.
This "works". It feels wrong and I'd love to see a better method.
Here's what I did:
Defined the plugin in the build section with the javadoc goal.
made sure tools.jar and rt.jar are in the <bootclasspath>
defined the <docletPath> as \;.;${project.build.outputDirectory};
the \;.; are necessary because maven doesn't append correctly
also had to explicitly add the path to some of the packages here to prevent inheritence of conflicting versions. (Specifically of Log4J)
defined <docletArtifacts> with the packages for the classes throwing the NoClassDefFoundError
My plugin now looks like this:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>build-siteMap-Descriptions</id>
<phase>process-classes</phase>
<goals>
<!--<goal>aggregate</goal>-->
<goal>javadoc</goal>
</goals>
<configuration>
<doclet>
us.ak.state.revenue.cssd.Personnel.utils.SiteMapDoclet
</doclet>
<!-- the initial '\;.;' is required
because maven doesn't separate the path statements properly
The 5 packages are necessary
because otherwise slf4j complains about multiple bindings
-->
<docletPath>
\;.;${project.build.outputDirectory};
${m2Repository}/commons-logging/commons-logging/1.1.1/commons-logging-1.1.1.jar;
${m2Repository}/log4j/log4j/1.2.16/log4j-1.2.16.jar;
${m2Repository}/log4j/apache-log4j-extras/1.1/apache-log4j-extras-1.1.jar;
${m2Repository}/us/ak/state/revenue/cssd/CSSD-Web/${CSSDWebBase.version}/CSSD-Web-${CSSDWebBase.version}.jar;
${m2Repository}/org/apache/wicket/wicket-core/${wicket.version}/wicket-core-${wicket.version}.jar;
${m2Repository}/org/apache/wicket/wicket-util/${wicket.version}/wicket-util-${wicket.version}.jar;
</docletPath>
<docletArtifacts>
<!--
<docletArtifact>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
<version>1.1.1</version>
</docletArtifact>
-->
<docletArtifact>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>1.6.2</version>
</docletArtifact>
<!-- how do I fix the download errors? -->
<!--
<docletArtifact>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.6.2</version>
</docletArtifact>
-->
<!--
<artifact>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.16</version>
</artifact>
-->
<!--
<docletArtifact>
<groupId>log4j</groupId>
<artifactId>apache-log4j-extras</artifactId>
<version>1.1</version>
</docletArtifact>
<docletArtifact>
<groupId>us.ak.state.revenue.cssd</groupId>
<artifactId>CSSD-Web</artifactId>
<version>${CSSDWebBase.version}</version>
</docletArtifact>
<docletArtifact>
<groupId>org.apache.wicket</groupId>
<artifactId>wicket-core</artifactId>
<version>${wicket.version}</version>
</docletArtifact>
-->
</docletArtifacts>
<!-- the initial '\;.;' is required
because maven doesn't separate the path statements properly -->
<bootclasspath>
\;.;
${bootClassPath};
${env.CLASSPATH};
</bootclasspath>
<destDir>SiteMap</destDir>
<author>false</author>
<!-- don't print the packages/classes it's running on -->
<quiet>true</quiet>
<debug>true</debug> <!-- save options -->
<useStandardDocletOptions>false</useStandardDocletOptions>
<name>SiteMapDoclet</name>
<description>Page Descriptions for SiteMap generation</description>
</configuration>
</execution>
</executions>
</plugin>

how to exclude GWT dependency code from OSGI bundle generated by MAven+BND?

I have several Maven modules with Vaadin library dependency in the root pom.xml file.
I'm trying to build a set of OSGI bundles (1 per Maven module) using Maven+BND.
I added this to my "root" pom.xml file:
<dependencies>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin</artifactId>
<version>6.6.6</version>
</dependency>
<dependency>
<groupId>com.google.gwt</groupId>
<artifactId>gwt-user</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>org.apache.felix</groupId>
<artifactId>org.osgi.core</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
unfortunately, the resulting JAR files (bundles) include GWT (com.google.gwt) classes. This
1) makes the bundles huge, with lots of duplicated dependencies.
2) generated thousands of build warnings about "split packages".
QUESTION: how to prevent adding GWT classes into my Jar files?
I tried setting "scope" of GWT to "provided", setting "type" to "bundle", and even optional=true - didn't help.
here's the part of my root pom.xml, which is responsible for Vaadin/GWT stuff:
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>2.3.5</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Export-Package>mycompany.*</Export-Package>
<Private-Package>*.impl.*</Private-Package>
<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
<!-- <Bundle-Activator>com.alskor.publicpackage.MyActivator</Bundle-Activator>-->
</instructions>
</configuration>
</plugin>
<!-- Compiles your custom GWT components with the GWT compiler -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>gwt-maven-plugin</artifactId>
<!-- Version 2.1.0-1 works at least with Vaadin 6.5 -->
<version>2.3.0-1</version>
<configuration>
<!-- if you don't specify any modules, the plugin will find them -->
<!--modules>
..
</modules-->
<webappDirectory>${project.build.directory}/${project.build.finalName}/VAADIN/widgetsets
</webappDirectory>
<extraJvmArgs>-Xmx512M -Xss1024k</extraJvmArgs>
<runTarget>clean</runTarget>
<hostedWebapp>${project.build.directory}/${project.build.finalName}</hostedWebapp>
<noServer>true</noServer>
<port>8080</port>
</configuration>
<executions>
<execution>
<goals>
<goal>resources</goal>
<goal>compile</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- Updates Vaadin 6.2+ widgetset definitions based on project dependencies -->
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
<version>1.0.1</version>
<executions>
<execution>
<configuration>
<!-- if you don't specify any modules, the plugin will find them -->
<!--
<modules>
<module>${package}.gwt.MyWidgetSet</module>
</modules>
-->
</configuration>
<goals>
<goal>update-widgetset</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
The wildcards in your Export-Package and Private-Package statements strike me as exceedingly dangerous. It's possible that the GWT packages are being dragged in because of the *.impl.* pattern in Private-Package.
Also you should never use wildcards in Export-Package: exports should be tightly controlled and versioned.
use mvn dependency:tree to see where the gwt dependency comes from
Add an <excludes/> element with an appropriate <exclude/> to the dependency in question to suppress it.
I've had similar problem, as final war file exceeded almost 90MB !
One of the culprit was aforementioned jar, so I did this :
<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>widgetset</artifactId>
<version>3.2</version>
<exclusions>
<exclusion>
<groupId>com.vaadin.external.gwt</groupId>
<artifactId>gwt-user</artifactId>
</exclusion>
</exclusions>
</dependency>
...
</dependencies>

Resources