JarCasting
JarCasting JarCasting

Javadoc to Swagger OpenAPI @Schema annotations enricher

Library and command line for scanning a source path and sub directories and adding or setting the "description" property of the Swagger OpenAPI @Schema annotation from the Javadoc.

License

License
GroupId

GroupId

de.ohmesoftware
ArtifactId

ArtifactId

javadoctoopenapischema
Last Version

Last Version

0.0.2
Release Date

Release Date
Type

Type

jar
Description

Description

Javadoc to Swagger OpenAPI @Schema annotations enricher
Library and command line for scanning a source path and sub directories and adding or setting the "description" property of the Swagger OpenAPI @Schema annotation from the Javadoc.
Project URL

Project URL

https://github.com/kaoh/javadoctoopenapischema
Source Code Management

Source Code Management

https://github.com/kaoh/javadoctoopenapischema/tree/master

Download javadoctoopenapischema

Filename Size
javadoctoopenapischema-0.0.2.pom
javadoctoopenapischema-0.0.2.jar 18 KB
javadoctoopenapischema-0.0.2-sources.jar 9 KB
javadoctoopenapischema-0.0.2-javadoc.jar 24 KB
Browse

How to add to project

<!-- https://jarcasting.com/artifacts/de.ohmesoftware/javadoctoopenapischema/ -->
<dependency>
    <groupId>de.ohmesoftware</groupId>
    <artifactId>javadoctoopenapischema</artifactId>
    <version>0.0.2</version>
</dependency>
// https://jarcasting.com/artifacts/de.ohmesoftware/javadoctoopenapischema/
implementation 'de.ohmesoftware:javadoctoopenapischema:0.0.2'
// https://jarcasting.com/artifacts/de.ohmesoftware/javadoctoopenapischema/
implementation ("de.ohmesoftware:javadoctoopenapischema:0.0.2")
'de.ohmesoftware:javadoctoopenapischema:jar:0.0.2'
<dependency org="de.ohmesoftware" name="javadoctoopenapischema" rev="0.0.2">
  <artifact name="javadoctoopenapischema" type="jar" />
</dependency>
@Grapes(
@Grab(group='de.ohmesoftware', module='javadoctoopenapischema', version='0.0.2')
)
libraryDependencies += "de.ohmesoftware" % "javadoctoopenapischema" % "0.0.2"
[de.ohmesoftware/javadoctoopenapischema "0.0.2"]

Dependencies

compile (2)

Group / Artifact Type Version
com.github.javaparser : javaparser-symbol-solver-core jar 3.12.0
org.apache.logging.log4j : log4j-slf4j-impl jar 2.11.2

test (5)

Group / Artifact Type Version
junit : junit jar 4.12
commons-io : commons-io jar 2.6
io.swagger.core.v3 : swagger-annotations jar 2.0.8
javax.persistence : javax.persistence-api jar 2.2
javax.validation : validation-api jar 2.0.1.Final

Project Modules

There are no modules declared in this project.

Introduction

Library and command line for scanning a source path and sub directories and adding or setting the description property of the Swagger OpenAPI @io.swagger.v3.oas.annotations.media.Schema annotation from the Javadoc.

Features

The library in its current state was created for setting the data model documentation of entities or DTOs.

Supported:

  • Javadoc parsing for summary and description for field and getters. Field have priority over getters.
  • Min, Max, Size, Column, NotEmpty, NotNull annotations
  • HATEAOS URI descriptions following the HAL specification targeting Spring REST data (hateaosHAL flag).

Limitations:

  • No internal enums are found.

Usage

Options

  • sourcePath: source path
  • includes: Restriction to include only the given file pattern. Multiples are separated by a comma.
  • excludes: Restriction to exclude the given file pattern. Multiples are separated by a comma.
  • hateaosHAL: In this case associations are rendered as links like common for HATEAOS.

NOTE: The excludes and includes options is using a glob expression. Take note that to use a wildcard over path separators two asterisks have to be used.

Java

Enricher enricher = new Enricher(buildPath(User.class.getPackage().getName()),
            Collections.singleton("**User.java"), Collections.singleton("**.bak"), false);
enricher.enrich();

Maven

    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.0.0</version>
        <executions>
          <execution>
            <goals>
              <goal>java</goal>
            </goals>
            <phase>generate-sources</phase>
          </execution>
        </executions>
        <configuration>
          <mainClass>de.ohmesoftware.javadoctoopenapischema.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>**User.java</argument>
          </arguments>
        </configuration>
        <dependencies>
            <dependency>
                <groupId>de.ohmesoftware</groupId>
                <artifactId>javadoctoopenapischema</artifactId>
                <version>0.0.2</version>
            </dependency>
        </dependencies>
    </plugin>

NOTE: It might be necessary because of a Log4j2 or exec-maven-plugin issue to add <cleanupDaemonThreads>false</cleanupDaemonThreads> to the <configuration> section.

NOTE: In case the central repository is not used, he exec-maven-plugin cannot be found. Include in this case:

    <repositories>
        ...
        <repository>
            <id>central</id>
            <url>https://repo1.maven.org/maven2/</url>
        </repository>
    </repositories>

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

NOTE: For the release step a PGP key is needed. To specify the used PGP key use:

mvn release:perform "-Dgpg.keyname=C168D0FD480DE80D8E2BDF08051E4014CED6947A"

or set the default key in .gnupg/gpg.conf:

default-key C168D0FD480DE80D8E2BDF08051E4014CED6947A

Release the deployment using Nexus See https://central.sonatype.org/pages/releasing-the-deployment.html Or do it with Maven:

cd target/checkout
mvn nexus-staging:release

Versions

Version
0.0.2
0.0.1