Generate Swagger out of REST-API Backends (v0.4)

Introduction

The normal way of creating Swagger documentation from Java source code would be Swagger Core annotations. But there are some issues with them.

First, Swagger annotations are compiled into the JAR / WAR of your server and consume disk space. Second, they do not look good. Last, there is much redundant data if you document your code with Javadoc and Swagger annotations. So there is more work for developers.

With this Swagger-Generation-Tool it is possible to place Swagger information into the Javadoc and generate with this information a Swagger documentation.

Configuration

Include this plugin into the pom.xml of the project:

<build>
	...
	<plugins>
		...
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-javadoc-plugin</artifactId>
			<version>VERSION</version>
			<configuration>
				<doclet>com.spirit21.Doclet</doclet>
				
				<docletArtifact>
					<groupId>com.spirit21.swagger</groupId>
					<artifactId>javadoc2swagger</artifactId>
					<version>0.4</version>
				</docletArtifact>
				
				<useStandardDocletOptions>false</useStandardDocletOptions>
				<additionalparam>-backend BACKEND_TYPE</additionalparam>
			</configuration>
		</plugin>
		...
	</plugins>
</build>

You can look up the version of the maven-javadoc-plugin here.

Parameters

Additional Parameters

These are all parameters and they can be set like it is shown in this example:

Name	Description	Possible Values	Default Value	Required
‑backend	This parameter determines whether it generates the Swagger file for a Spring Boot project or for a JAX-RS project. This parameter is required. When the parameter is invalid or is not set, this tool throws an exception.	spring jaxrs	None	Yes
-version	This parameter determines whether the tool should use the Swagger version 2 or 3. This parameter is not required. When the parameter is invalid or is not set, this tool takes the default value.	2 3	3	No
-type	This parameter determines whether the tool should generate a .yaml or a .json file. This parameter is not required. When the parameter is invalid or is not set, this tool takes the default value.	json yaml	json	No
‑filename	This parameter sets the name of the file which will be generated. If you do not use this parameter this program will use the name out your code at the starting point out of your application (see here or here). If there is not any file name given the default value will be used.	Everything you want	the value out of your code or 'generated-swagger'	No

These parameters can be set like it is shown in this example:

<additionalparam>-backend spring -type yaml -version 3 -filename openapi</additionalparam>

Parameters between the configuration-tags

There are several tags you can put between the configuration tags. For example you can specify the output directory.

For more information please read the documentation here: Parameters

Usage

Usage with other dependencies

If you want to include the source files of dependencies, then please include these tags between the configuration tags:

<includeDependencySources>true</includeDependencySources>
<dependencySourceIncludes>
	<dependencySourceInclude>GROUP_ID:*</dependencySourceInclude>
	<dependencySourceInclude>...</dependencySourceInclude>
</dependencySourceIncludes>

If the source artifact is unavailable you have to prepare the dependency. You have to put this plugin into the pom.xml of the dependency:

<plugin>
	<artifactId>maven-source-plugin</artifactId>
	<version>2.1.1</version>
	<executions>
   		<execution>
      		<id>bundle-sources</id>
         	<phase>package</phase>
			<goals>
				<!-- produce source artifact for main project sources -->
				<goal>jar-no-fork</goal>
				<!-- produce source artifact for project test sources -->
				<goal>test-jar-no-fork</goal>
			</goals>
		</execution>
	</executions>
</plugin>

Execute this project with mvn clean install in the command line.

After this is done you can include the dependency as mentioned above and execute the command mvn javadoc:aggregate on the project in the command line.

Usage without other dependencies

Without other dependencies you do not need any extra configuration. Just run mvn javadoc:javadoc on the project in the command line.

How this Swagger Generation Tool works

This tool generates a Swagger file by executing the above mentioned command. This tool looks for specific information. Where the information must be located and how the information should look like you can find in the specific project which you find below:

Swagger Generation out of a JAX-RS Backend

This subproject creates a Swagger file out of a JAX-RS REST-API.

You find more information here: javadoc-jaxrs-swagger-doclet

Swagger Generation out of a Spring Boot Backend

This subproject creates a Swagger file of a Spring Boot REST-API.

You find more information here: javadoc-springboot-swagger-doclet