Plugin to ease developing and documenting REST services
Usage
Status
Releases
Requirements
Overview
Related projects
The plugin has many goals - the rip
goal is a meta-goal that call most of the others.
The rip
goal was the motivation for creating this plugin: one plugin to handle all swagger related stuff.
The rip
goal has not yet been tested on a server with security enabled.
If problems occur I suggest you create your swagger.json and and swagger-ui (using fx springdoc)
and then use the rip-maven plugin with the following goals:
generateRest
, generateClient
and perhaps diff
.
<plugin>
<groupId>com.github.hervian</groupId>
<artifactId>rip-maven-plugin</artifactId>
<version>${project.parent.version}</version>
<configuration>
<generateDocConfig> <!-- each mojo has a corresdponding config tag. See code for details. -->
<additionalDocs>
<additionalDoc>HTML2</additionalDoc>
</additionalDocs>
</generateDocConfig>
<diffConfig>
<skipCheckForBreakingChanges>true</skipCheckForBreakingChanges> <-- the API breaking changes check is not yet fully tested -->
</diffConfig>
<generateClientConfig>
<languages>
<language>JAVA</language>
<language>DART</language>
</languages>
</generateClientConfig>
</configuration>
<executions>
<execution>
<goals>
<goal>generateRest</goal> <!-- Collects openapi generator clients from classpath and makes them available in an autogenerated Rest class: `Rest.webclientServerClient().factsApi().getRandomFact()` -->
<goal>rip</goal> <!-- autogenerates swagger.json doc, an endpoint to expose it, swagger-ui, a client for your server and performs and asserts that pom's major version has been increased if there has been breaking changes introduced -->
</goals>
</execution>
</executions>
</plugin>
Proof-of-concept.
The project is not yet production ready since testing is still ongoing.
Not yet released to maven repo since this is currently a POC.
TODO The project has been compiled and tested with jdk18 and spring boot 3. See the pom.xml of the various modules in the project.
I don't yet have an overview of the compatibilty. One could fx consider if it was possible to set the target java version to something lower than java 18. Guide on the matter: https://www.baeldung.com/java-source-target-options
The plugin provide the following maven goals:
- generateRest (bound to precompile phase as opposed to all the other goals that run after compilation)
- diff
- generateDoc
- generateUi
- generateClient
- rip: meta goal - calls diff, generateDoc, generateUi and generateClient
The rip-maven-plugin is a "meta-plugin", so to speak. It calls a lot of other plugins. TODO - list the projects being used
Create a setup that deploys to github packages. Test that 'mvn clean deploy' also deploys the generated clients. See https://stackoverflow.com/questions/59093341/how-do-you-upload-a-maven-artifact-to-github-packages-using-the-command-line
Test if a pure rip-maven-plugin setup works with spring-security etc.
Change generateRestDoc - restAnnotationType should only relate to the annotations The config of download of json vs generation of json should be a separate param.
Code cleanup - search for "TODO"
Make thread-safe and consider if concurrent execution of some of the goals is possible