使用springfox 集成swagger 与spring mvc

创建一个maven 模块
将springfox相关的配置都配置在一个单独的api模块中，可以把这个模块当成web应用跑起来。

<pluginRepositories>
<pluginRepository>
<id>jcenter-snapshots</id>
<name>jcenter</name>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
</pluginRepository>
<pluginRepository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</pluginRepository>
</pluginRepositories>

<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
<repository>
<id>jcenter-snapshots</id>
<name>jcenter</name>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
</repository>
</repositories>

<dependencies>
<!--<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>${springframework.version}</version>
<scope>provided</scope>
</dependency>-->
<!--<dependency>
<groupId>nl.jworks.markdown_to_asciidoc</groupId>
<artifactId>markdown_to_asciidoc</artifactId>
<version>1.0</version>
</dependency>-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>

<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.0.1</version>
</dependency>
<!--api-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.6.3</version>
</dependency>
<dependency>
<!--项目模块-->
<groupId>com.inlycat</groupId>
<artifactId>yixun-core</artifactId>
<version>1.0</version>
</dependency>
<dependency>
<!--项目模块-->
<groupId>com.inlycat</groupId>
<artifactId>yixun-app</artifactId>
<version>1.0</version>
<type>war</type>
</dependency>

<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-staticdocs</artifactId>
<version>2.4.0</version>
</dependency>
</dependencies>

<build>
<plugins>
<!--可以将文档导出md文件，不过目前导出时会报错-->
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.0.0</version>
<configuration>
<swaggerInput>http://localhost:8081/api/v2/api-docs?group=external</swaggerInput>
<outputDir>${project.build.directory}/asciidoc</outputDir>
<config>
<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
</config>
</configuration>
</plugin>
</plugins>
<finalName>${project.name}</finalName>
</build>
```
2. 在需要引入swagger注解的模块中引入相应的依赖。
```
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.6.3</version>
</dependency>
</dependencies>
```
3. 在api模块中添加初始化swagger的代码。
```
@EnableSwagger2
public class Swagger2Spring {
@Bean
public Docket petApi() {
return new Docket(DocumentationType.SWAGGER_2);
}
```
api模块也是一个spring mvc 项目，在spring mvc 的配置文件中加入代码。
```
<mvc:annotation-driven/>
<!--需要扫描的controller-->
<context:component-scan base-package="cn.com.yixun.**.api" use-default-filters="false" >
<context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/>
</context:component-scan>
<!-- Enables swgger ui-->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

<!-- Include a swagger configuration-->
<bean name="/applicationSwaggerConfig" class="cn.com.yixun.doc.swagger.Swagger2Spring"/>

启动项目之后打开网址，{项目地址}/swagger-ui.html 就可以访问了。

后记：由于swagger对项目的侵入性比较强，可以考虑把注解写在接口上。