This Maven Plugin is generating a Swagger API documentation for JAX-RS based Java servers. Additional information that is not contained in JAX-RS annotations is placed in the Javadoc comments.
A sample Maven project using the javadoc2swagger-maven-plugin
is available here:
https://github.com/SPIRIT-21/javadoc2swagger-examples
The normal way of creating a 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 don't look good. Third, there are redundant data if you are both documenting your code with Javadoc and using Swagger Annotations, so there is more work for developers to maintain them.
With this plugin it is possible to place Swagger information in the Javadoc comments to generate a Swagger documentation.
Include the plugin to your POM:
<plugin>
<groupId>com.spirit21</groupId>
<artifactId>javadoc2swagger-maven-plugin</artifactId>
<version>VERSION</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generateswagger</goal>
</goals>
</execution>
</executions>
</plugin>
If you want the Swagger file to be added to your JAR / WAR, use the maven-jar-plugin
/ maven-war-plugin
. The following example adds all JSON files located in the target/swagger
folder to the root directory of the created WAR:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>3.0.0</version>
<configuration>
<webResources>
<resource>
<directory>target/swagger</directory>
<includes>
<include>*.json</include>
</includes>
</resource>
</webResources>
</configuration>
</plugin>
To execute the plugin, initiate the Maven compile phase, e.g. by executing mvn clean install
in the command line.
For a valid Swagger documentation, you need to at least provide a title. Place your basic API information anywhere in your Javadoc comments like in this example:
/**
* @apiTitle API title
* @apiVersion version1
* @apiDescription API description
* @apiHost localhost:8080
* @apiBasePath /example/api/v1
* @fileName swagger-file-name.json
*/
For defining a resource, a path must be provided. When using a path parameter, its format must be defined. This information needs to be placed in the Javadoc of the class definition, like in the following example:
/**
* @path /type/{id}
* @pathParam id @type number @format long
*/
public class ...
When using multiple path parameters, please ensure that the @format
tag is always given. If you don't want to specify a format, leave the text behind the tag empty. Example:
/**
* @path /type/{id}/{childId}
* @pathParam id @type string @format
* @pathParam childId @type number @format long
*/
public class ...
An operation must be defined in the same file as its resource! Otherwise the operation will be ignored because it cannot be assigned to a resource.
The plugin detects the JAX-RS HTTP-method annotations and the @Produces
/ @Consumes
annotations by itself.
Parameters are obtained by the parameter list of the java function. Use the @QueryParam
annotation for query parameters. If you don't want a parameter to be included in the Swagger documentation, paste the following comment: /* @swagger:ignore */
. Following example ignores the date
parameter:
public Response updateType(Type type, /* @swagger:ignore */ Date date) { ...
If you want to provide a description for a parameter, use the built-in @param
Javadoc tag, followed by the name and finally the description.
Responses have to be defined in the Javadoc code. Use the tags @responseCode
and @responseMessage
. Provide a schema of your response type with the tag @responseSchema
followed by a link tag pointing to the class with the schema. Use the tag @responseType
followed by array
if an array of object is returned. Following example uses all possible tags:
/**
* @responseCode 201
* @responseMessage Types were returned successfully
* @responseSchema {@link Type}
* @responseType array
*
* @responseCode 400
* @responseMessage An error occurred while validation
* @responseSchema {@link ErrorCode}
*/
Following section lists some errors that might occure when executing the plugin and how to fix them.
- "You need to provide information about your API! Title is required."
- Solution: Add an API information block in the Javadoc with at least a title.
- "Multiple API information Javadoc sections found!"
- Solution: Remove duplicate API information blocks.
- "Error loading Class className"
- An error occured while loading the specified class.
- Solution: The plugin is only able to 'see' the source code from the project in which it is executed. When a class from another project is not being found, simply pass the project to the plugin as dependency, like in the following example:
<plugin>
<groupId>com.spirit21</groupId>
<artifactId>javadoc2swagger-maven-plugin</artifactId>
...
<dependencies>
<dependency>
<groupId>GROUP-ID</groupId>
<artifactId>ARTIFACT-ID</artifactId>
<version>VERSION</version>
</dependency>
</dependencies>
</plugin>
If the error persists, you can ignore the whole Java file by placing the following somewhere in the Javadoc comments: @swagger:ignore_javafile
. This doesn't fix the problem but allows you to still create Swagger for all your other Java files.
- "java.lang.IndexOutOfBoundsException: Index: 1, Size: 1"
- Solution: When using multiple path parameters in one path, always provide a parameter format. If you don't want to specify a format, leave the text behind the
@format
tag empty.
- Solution: When using multiple path parameters in one path, always provide a parameter format. If you don't want to specify a format, leave the text behind the