com.spirit21.swagger:javadoc2swagger

An application used to generate Swagger files out of REST-API's.

License

License

Categories

Categories

Swagger Program Interface REST Frameworks
GroupId

GroupId

com.spirit21.swagger
ArtifactId

ArtifactId

javadoc2swagger
Last Version

Last Version

0.4
Release Date

Release Date

Type

Type

jar
Description

Description

An application used to generate Swagger files out of REST-API's.

Download javadoc2swagger

How to add to project

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

Dependencies

compile (4)

Group / Artifact Type Version
com.spirit21.swagger : swagger-doclet-common jar 0.3
com.spirit21.swagger : javadoc-springboot-swagger-doclet jar 0.3
com.spirit21.swagger : javadoc-jaxrs-swagger-doclet jar 0.3
io.swagger : swagger-parser-v2-converter jar 2.0.0-rc1

provided (1)

Group / Artifact Type Version
org.projectlombok : lombok jar 1.16.20

system (1)

Group / Artifact Type Version
com.sun » tools jar 1.8.0_144

Project Modules

There are no modules declared in this project.

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

com.spirit21.swagger

SPIRIT/21

Versions

Version
0.4
0.3