sb-rest-doclet

Spring boot javadoc doclet

License

License

Categories

Categories

Ant Build Tools
GroupId

GroupId

com.github.antonsjava
ArtifactId

ArtifactId

sb-rest-doclet
Last Version

Last Version

1.7
Release Date

Release Date

Type

Type

jar
Description

Description

sb-rest-doclet
Spring boot javadoc doclet
Project URL

Project URL

https://github.com/antonsjava/sb-rest-doclet
Source Code Management

Source Code Management

https://github.com/antonsjava/sb-rest-doclet

Download sb-rest-doclet

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.antonsjava/sb-rest-doclet/ -->
<dependency>
    <groupId>com.github.antonsjava</groupId>
    <artifactId>sb-rest-doclet</artifactId>
    <version>1.7</version>
</dependency>
// https://jarcasting.com/artifacts/com.github.antonsjava/sb-rest-doclet/
implementation 'com.github.antonsjava:sb-rest-doclet:1.7'
// https://jarcasting.com/artifacts/com.github.antonsjava/sb-rest-doclet/
implementation ("com.github.antonsjava:sb-rest-doclet:1.7")
'com.github.antonsjava:sb-rest-doclet:jar:1.7'
<dependency org="com.github.antonsjava" name="sb-rest-doclet" rev="1.7">
  <artifact name="sb-rest-doclet" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.github.antonsjava', module='sb-rest-doclet', version='1.7')
)
libraryDependencies += "com.github.antonsjava" % "sb-rest-doclet" % "1.7"
[com.github.antonsjava/sb-rest-doclet "1.7"]

Dependencies

compile (3)

Group / Artifact Type Version
com.github.antonsjava : jaul jar 1.19
com.fasterxml.jackson.core : jackson-databind jar 2.10.5.1
com.fasterxml.jackson.datatype : jackson-datatype-jsr310 jar 2.10.5

test (1)

Group / Artifact Type Version
junit : junit jar 4.13.1

Project Modules

There are no modules declared in this project.

sb-rest-doclet

Spring boot rest javadoc doclet

Motivation

I was unable to find maven plugin which generates simple static documentation of spring boot rest API.

I was using enunciate plugin but I missed some trivial features like transfer javadoc info to generated documentation.

Excuse

I provide this software as open source, but it is horrible code. Doclet API is purely documented and I have no strength to fix the code after I make it runnable. (maybe later)

I publish it only to have possibility to put it to maven central repo so I can use it.

So please excuse me.

Basic configuration

Configuration of doclet itself is still surprising me. I must enable standard doclet configuration in plugin to make it working at all. But I'm reflecting only

  • -d (./target/site/apidocs)
  • -docencoding (UTF-8)

Basic usage

In your spring boot module with REST API you can use plugin in this form It generate documentation for controller classes in this module and model classes which are in this module only.

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-javadoc-plugin</artifactId>
   <version>3.2.0</version>
   <configuration>
       <doclet>sk.antons.sb.rest.doclet.SBRestDoclet</doclet>
       <docletArtifacts>
           <docletArtifact>
               <groupId>com.github.antonsjava</groupId>
               <artifactId>sb-rest-doclet</artifactId>
               <version>1.3</version>
           </docletArtifact>
       </docletArtifacts>
       <useStandardDocletOptions>true</useStandardDocletOptions>
   </configuration>
 </plugin>

Multimodule usage

In your spring boot module with REST API you can use plugin in this form It generate documentation for controller classes in this module and model classes which are in specified module. (It is necessary, that this module is explicitly listed as dependency of rest module)

(Don't use only includeDependencySources property but explicitly name that module too.)

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-javadoc-plugin</artifactId>
   <version>3.2.0</version>
   <configuration>
       <doclet>sk.antons.sb.rest.doclet.SBRestDoclet</doclet>
       <docletArtifacts>
           <docletArtifact>
               <groupId>com.github.antonsjava</groupId>
               <artifactId>sb-rest-doclet</artifactId>
               <version>1.3</version>
           </docletArtifact>
       </docletArtifacts>
       <useStandardDocletOptions>true</useStandardDocletOptions>
       <includeDependencySources>true</includeDependencySources>
       <dependencySourceIncludes>
           <dependencySourceInclude>camp.xit.kiwi.msender:msender-model:*</dependencySourceInclude>
       </dependencySourceIncludes>
   </configuration>
 </plugin>

Dummy json examples for model classes

You need to add model modul as doclet dependence using docletArtifact. In this way model classes can be instantiated and doclet generate json example using jackson object mapper.

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-javadoc-plugin</artifactId>
   <version>3.2.0</version>
   <configuration>
       <doclet>sk.antons.sb.rest.doclet.SBRestDoclet</doclet>
       <docletArtifacts>
           <docletArtifact>
               <groupId>com.github.antonsjava</groupId>
               <artifactId>sb-rest-doclet</artifactId>
               <version>1.3</version>
           </docletArtifact>
           <docletArtifact>
               <groupId>camp.xit.kiwi.msender</groupId>
               <artifactId>msender-model</artifactId>
               <version>${project.version}</version>
           </docletArtifact>
       </docletArtifacts>
       <useStandardDocletOptions>true</useStandardDocletOptions>
       <includeDependencySources>true</includeDependencySources>
       <dependencySourceIncludes>
           <dependencySourceInclude>camp.xit.kiwi.msender:msender-model:*</dependencySourceInclude>
       </dependencySourceIncludes>
   </configuration>
 </plugin>

Example

Simple project with pure documentation here

And resulted documentation here

You can download there files and look for them. You can also build example project and generate that documentation. (plugin geterate during deploy or directly start plugin mvn clean javadoc:javadoc)

Versions

Version
1.7
1.6
1.5
1.4
1.3
1.2
1.1
1.0