https://github.com/antonsjava/sb-rest-doclet
Spring boot rest doclet
https://github.com/antonsjava/sb-rest-doclet
Last synced: about 2 months ago
JSON representation
Spring boot rest doclet
- Host: GitHub
- URL: https://github.com/antonsjava/sb-rest-doclet
- Owner: antonsjava
- License: apache-2.0
- Created: 2020-04-13T18:00:57.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-12-17T17:49:11.000Z (over 1 year ago)
- Last Synced: 2025-02-01T21:17:27.776Z (4 months ago)
- Language: Java
- Size: 81.1 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
```xml
org.apache.maven.plugins
maven-javadoc-plugin
3.2.0
sk.antons.sb.rest.doclet.SBRestDoclet
${basedir}/target/classes
com.github.antonsjava
sb-rest-doclet
1.13
${project.groupId}
${project.artifactId}
${project.version}
true
true
${project.groupId}:${project.artifactId}:${project.version}
rest-doc
deploy
javadoc
```
## 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.)
```xml
org.apache.maven.plugins
maven-javadoc-plugin
3.2.0
sk.antons.sb.rest.doclet.SBRestDoclet
${basedir}/target/classes
com.github.antonsjava
sb-rest-doclet
1.3
${project.groupId}
${project.artifactId}
${project.version}
true
true
${project.groupId}:${project.artifactId}:${project.version}
camp.xit.kiwi.msender:msender-model:*
rest-doc
deploy
javadoc
```
## 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.
```xml
org.apache.maven.plugins
maven-javadoc-plugin
3.2.0
sk.antons.sb.rest.doclet.SBRestDoclet
${basedir}/target/classes
io.github.antonsjava
sb-rest-doclet
LASTVERSION
${project.groupId}
${project.artifactId}
${project.version}
camp.xit.kiwi.msender
msender-model
${project.version}
true
true
${project.groupId}:${project.artifactId}:${project.version}
camp.xit.kiwi.msender:msender-model:*
rest-doc
deploy
javadoc
```
## Example
Simple project with pure documentation [here](./example/sb-rest-doclet-example)
And resulted documentation [here](./example/sb-rest-doclet-example-result/site/apidocs/index-rest.html)
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)