This plugin enables your Swagger-annotated project to generate Swagger specs and customizable, templated static documents during the maven build phase. Unlike swagger-core, swagger-maven-plugin does not actively serve the spec with the rest of the application; it generates the spec as a build artifact to be used in downstream Swagger tooling.

• Supports Swagger Spec 2.0
• Supports SpringMvc & JAX-RS
• Quickly generates swagger.json and static document by mvn compile
• Use Handlebars as template to customize the static document.

• 3.1.0 supports Swagger Spec [2.0](https://github .com/swagger-api/swagger-spec/blob/master/versions/2.0.md), support JAX-RS & SpingMVC. (ACTIVE!)
• 3.0.1 supports Swagger Spec [2.0](https://github .com/swagger-api/swagger-spec/blob/master/versions/2.0.md), support JAX-RS & SpingMVC. (ACTIVE!)
• 2.3.4 supports Swagger Spec 1.2, support JAX-RS & SpringMVC. (Lazily maintained)
• 1.1.1 supports Swagger Spec 1.1. (No longer maintained)

Version 3.1.0+ of this plugin depends on the repackaged/rebranded io.swagger.swagger-core dependency, which is formerly known as com.wordnik.swagger-core. If you use 3.1.0+, you must use the swagger-core dependency in the io.swagger namespace instead of the com.wordnik namespace, which is deprecated. You may see an example of migrating a project from 3.0.1 to 3.1.0 in the swagger-maven-plugin example project.

Import the plugin in your project by adding following configuration in your plugins block:

<build>
	<plugins>
		<plugin>
			<groupId>com.github.kongchen</groupId>
			<artifactId>swagger-maven-plugin</artifactId>
			<version>${swagger-maven-plugin-version}</version>
			<configuration>
				<apiSources>
					<apiSource>
						...
					</apiSource>
				</apiSources>
			</configuration>
		</plugin>
	</plugins>
</build>

One apiSource can be considered as a version of APIs of your service.

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

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:

   1. classpath:/markdown.hbs
   2. classpath:/templates/hello.html

2. Local file's absolute path. e.g:

   1. ${basedir}/src/main/resources/markdown.hbs
   2. ${basedir}/src/main/resources/template/hello.html

There's a standalone project for the template files, fetch them and customize it for your own project.

There're 3 types of security definitions according to Swagger Spec: basic, apiKey and oauth2.

You can define multi definitions here, but you should fully follow the spec.

You can define a basic definition like this:

<securityDefinition>
    <name>MybasicAuth</name>
    <type>basic</type>
</securityDefinition>

or define several definitions in a json file and specify the json path like this:

<securityDefinition>
    <json>/securityDefinition.json</json>
</securityDefinition>

The file will be read by getClass().getResourceAsStream, so please note the path you configured.

The securityDefinition.json file should also follow the spec, one sample file like this:

{
  "api_key": {
    "type": "apiKey",
    "name": "api_key",
    "in": "header"
  },
  "petstore_auth": {
    "type": "oauth2",
    "authorizationUrl": "http://swagger.io/api/oauth/dialog",
    "flow": "implicit",
    "scopes": {
      "write:pets": "modify pets in your account",
      "read:pets": "read your pets"
    }
  }
}

Throughout the course of working with Swagger, you may find that you need to substitute non-primitive objects for primitive objects. This is called model substituion, and it is supported by swagger-maven-plugin. In order to configure model substitution, you'll need to create a model substitute file. This file is a simple text file containing n lines, where each line tells swagger-maven-plugin to substitutes a model class with the supplied substitute. These two classes should be seperated by a colone (:).

com.foo.bar.PetName : java.lang.String

The above model substitution configuration would tell the plugin to substitute com.foo.bar.PetName with java.lang.String. As a result, the generated swagger.json would look like this ...

 "definitions" : {
    "Pet" : {
      "properties" : {
        ...
        "petName" : {
          "type" : "string"
        }
        ...
      }
    }

... instead of like this:

 "definitions" : {
    "Pet" : {
      "properties" : {
        ...
        "petName" : {
          "$ref" : "#/definitions/PetName"
        }
        ...
      }
    }

The model substitution file will be read by getClass().getResourceAsStream, so please note the path you configured.

You can instruct swagger-maven-plugin to skip processing the parameters of certain types by adding the following to your pom.xml:

<typesToSkip>
  <typeToSkip>com.foobar.skipper.SkipThisClassPlease</typeToSkip>
  <typeToSkip>com.foobar.skipper.AlsoSkipThisClassPlease</typeToSkip>
</typesToSkip>

This requires at least swagger-maven-plugin version 3.1.1-SNAPSHOT.

If you'd like to exclude certain @ApiModelPropertys based on their access values, you may do so by adding the following as a child node of apiSource in your pom.xml:

<apiModelPropertyAccessExclusions>
    <apiModelPropertyAccessExclusion>secret-property</apiModelPropertyAccessExclusion>
</apiModelPropertyAccessExclusions>

The above setting would prevent internalThing from appearing in the swagger spec output, given this annotated model:

...
    @ApiModelProperty(name = "internalThing", access = "secret-property")
    public String getInternalThing() {
        return internalThing;
    }
...

Note: In order to use apiModelPropertyAccessExclusions, you must specify both the name and access fields of the property you wish to exclude. Additionally, apiModelPropertyAccessExclusions requires at least swagger-maven-plugin version 3.1.1-SNAPSHOT.

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

<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>kongchen@gmail.com</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>
                <securityDefinitions>
                    <securityDefinition>
                        <name>basicAuth</name>
                        <type>basic</type>
                    </securityDefinition>
                    <securityDefinition>
                        <json>/securityDefinition.json</json>
                    </securityDefinition>
                </securityDefinitions>
                <!-- 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>

SNAPSHOT versions are available for verifing issues and new features. If you would like to try to verify the fixed issues or the new added features, you may need to add a pluginRepository node in your pom.xml:

<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>

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 then you can use <exclusion> configuration in pom.xml to exclude it.

Here's an example:

To 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>