rip-maven-plugin

Plugin to ease developing and documenting REST services

Table of Contents

Usage
Status
Releases
Requirements
Overview
Related projects

Usage

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>

Status

Proof-of-concept.
The project is not yet production ready since testing is still ongoing.

Releases

Not yet released to maven repo since this is currently a POC.

Requirements

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

Overview

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

Related projects

The rip-maven-plugin is a "meta-plugin", so to speak. It calls a lot of other plugins. TODO - list the projects being used

TODO

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