JarCastingIntroduction
Library and command line for scanning a source path and sub directories and adding or setting the Swagger OpenAPI io.swagger.v3.oas.annotations.Operation annotation for Spring Data REST.
Features
The library in its current state was created for setting the Operation documentation of Spring Data REST.
- Support for standard, POST, POUT, DELETE, PATCH, QueryDSL and standard PagingAndSortingRepository
findAllmethods - PUT can be disabled with the flag
disablePUT
Limitations:
- Only collection and item method resources are considered.
- Domain models must be classes. No interfaces are supported. Only fields will be inspected.
- No inner classes and inner enums are supported.
- The resolution of class names only works if no wild card imports are used.
- If own intermediate repository interfaces (e.g. for adding some default annotations) are used with generics, the domain class must be the first type parameter.
- The method
T update(T entity)is a reserved name in custom repositories. - To override methods in repositories a concrete type must be used, e.g to overwrite
<S extends T> S save(S entity)User save(User entity)must be used.
Usage
Spring Data REST does not use JAX-RS annotations but scans the offered repository interface methods using a naming convention for the method semantics. This semantics are also used by this library.
NOTE: The library will remove its own added methods and annotations as preparation. This should work flawlessly but keep a backup if this fails in some situations.
Source Code Preparation
- Apply the Spring REST
@RepositoryRestResourceand@Resourceannotations to the repository interfaces to set theexportedandpathproperty. This will be honored by this library. - To get non default Javadoc comments for the methods override the implementations in the concrete implementation
- The
Operationsummary is using the first part of the comment. - The
Operationdescription is using any text after a paragraph<p> @paramtags are used for the@Parameterdescription.
- The
- Mark overridden methods from the
CrudRepository,PagingAndSortingRepositoryandQuerydslPredicateExecutorwith@RestResource, otherwise they will be removed in the next run findById,findAll,deleteById, the create and the update method are using default descriptions if not explicitly defined.- Because
PUTfor updates and POST for creations are using both thesavemethod an additional marker method is added for thePUTcall. AnT update(T entity)method is added to a custom repository interface, which is created if it does not exists yet. Some applies forPATCHcalls. - Custom repositories can use arbitrary method namings. Also the returned content and HTTP method cannot be determined. All
Operationand JAX-RS annotations must be manually added. - Add a proprietary
SearchableandSortableannotations to define the sort and search parameters and pass this assearchableAnnotationandsortableAnnotation:
@Inherited
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Sortable {
String[] value();
}
@Inherited
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Searchable {
String[] value();
}
Library Execution
- Pass the source path with excludes and includes to the library or the Main class
- NOTE: The
excludeandincludeoptions are using a glob expression. Take note that to use a wild card over path separators two asterisks have to be used.
- NOTE: The
Java
Enricher enricher = new Enricher(buildPath(User.class.getPackage().getName()),
Collections.singleton("**UserRepository.java"), Collections.singleton("**.bak"), false, null, null);
enricher.enrich();
Maven
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.6.0</version>
<executions>
<execution>
<goals>
<goal>java</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<mainClass>de.ohmesoftware.springdataresttoopenapischema.Enricher</mainClass>
<includePluginDependencies>true</includePluginDependencies>
<arguments>
<argument>-sourcePath</argument>
<argument>src/test/java/my/domain/project/model</argument>
<argument>-excludes</argument>
<argument>**.bak</argument>
<argument>-includes</argument>
<argument>**UserRepository.java</argument>
<argument>-searchableAnnotation</argument>
<argument>my.path.Searchable</argument>
<argument>-sortableAnnotation</argument>
<argument>my.path.Searchable</argument>
</arguments>
</configuration>
<dependencies>
<dependency>
<groupId>de.ohmesoftware</groupId>
<artifactId>springdataresttoopenapischema</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
</dependencies>
</plugin>
Deployment + Release
See https://central.sonatype.org/pages/apache-maven.html
For Snapshots
mvn clean deploy
For Releases
mvn release:clean release:prepare
mvn release:perform
Release the deployment using Nexus See https://central.sonatype.org/pages/releasing-the-deployment.html Or alternatively do it with Maven:
cd target/checkout
mvn nexus-staging:release