Swagger Maven Plugin

This plugin can let your Swagger annotated project generate Swagger JSON and your customized API documents in build phase.

Swagger JSON is a json file which represents your APIs fully follows Swagger Spec 2.0.

Customized API document looks like this:

Example

There's a sample here, just fork it and have a try.

Configurations for Swagger JSON

<project>
...
<build>
<plugins>
<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
        <apiSources>
            <apiSource>
	            <springmvc>true</springmvc>
                <locations>com.wordnik.swagger.sample</locations>
                <schemes>http,https</schemes>
                <host>www.example.com:8080</host>
                <basePath>/api</basePath>
                <info>
                    <title>Swagger Maven Plugin Sample</title>
                    <version>v1</version>
                    <!-- use markdown here because I'm using markdown for output,
                    if you need to use html or other markup language, you need to use your target language,
                     and note escape your description for xml -->
                    <description>
                        This is a sample.
                    </description>
                    <termsOfService>
                        http://www.github.com/kongchen/swagger-maven-plugin
                    </termsOfService>
                    <contact>
                        <email>[email protected]</email>
                        <name>Kong Chen</name>
                        <url>http://kongch.com</url>
                    </contact>
                    <license>
                        <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
                        <name>Apache 2.0</name>
                    </license>
                </info>
                <!-- Support classpath or file absolute path here.
                1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html"
                2) file e.g: "${basedir}/src/main/resources/markdown.hbs",
                    "${basedir}/src/main/resources/template/hello.html" -->
                <templatePath>${basedir}/src/test/resources/strapdown.html.hbs</templatePath>
                <outputPath>${basedir}/generated/document.html</outputPath>
                <swaggerDirectory>${basedir}/generated/swagger-ui</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>
...
</plugins>
</build>
</project>

If you cannot wait to try out the plugin, here's a sample project, go to see how it happens.

You can specify several apiSources. Generally, one is enough.

One apiSource can be considered as a set of APIs. Here's the required parameters for an apiSource:

Required parameters

name	description
springmvc	Tell the plugin your project is a jaxrs or a SpringMvc project
locations	Java classes containing Swagger's annotation @Api, or Java packages containing those classes can be configured here, using ; as the delimiter.
info	The basic information of the api, the field version and title are required.
schemes	The supported schemes of the api source.
host	The hostname and port of the api service.
basePath	The base path of this api source.

Optional parameters

name	description
templatePath	The path of a handlebars template file, see more details below.
outputPath	The path of the output document, not existed parent directories will be created. If you don't want to generate html api just don't set it.
swaggerDirectory	The directory of generated Swagger JSON files. If null, no Swagger JSON will be generated. The final output swagger json would be ${swaggerDirectory}/swagger.json

About the template file

You need to specify a handlebars template file in templatePath. The value for templatePath supports 2 kinds of path:

1. Resource in classpath. You should specify a resource path with a classpath: prefix. e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html"
2. Local file path. e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/template/hello.html"

To display swagger.json correctly, there're 2 new helpers added in. For more details see the template files.

There's a standalone project for the template files, see more details there and welcome to send pull request.

Versions

This plugin has 3 serials of versions:

• 3.x.x : For Swagger spec 2.0

Latest version 3.0.0-SNAPSHOT

• 2.x.x : For swagger-spec 1.2

Latest version 2.3.1 is available in central repository. 2.3.1-SNAPSHOT is the latest SNAPSHOT version.

• 1.x.x : For Swagger core version 1.2.x swagger-spec 1.1

Latest version 1.1.3-SNAPSHOT is available in sonatype repository.

To use SNAPSHOT version, you need to add plugin repository in your pom.xml first:

<pluginRepositories>
  <pluginRepository>
    <id>sonatype-snapshot</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </pluginRepository>
</pluginRepositories>

FAQ

Dependency conflict

If you have package depedency conflict issues, such as jackson, joda-time, or jsr311-api. Run mvn dependency:tree to check which package introduces the one conflicts with yours and exclude it using <exclusion/> in pom.xml.

e.g. exclude javax.ws.rs:jsr311-api:jar:1.1.1:compile from swagger-jaxrs_2.10:

    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-jaxrs_2.10</artifactId>
        <version>1.3.2</version>
        <exclusions>
            <exclusion>
                <groupId>javax.ws.rs</groupId>
                <artifactId>jsr311-api</artifactId>
            </exclusion>
        </exclusions>
    </dependency>