使用springfox 集成swagger 与spring mvc

超强辅助 Bolt.diy ⼀步搞定创意建站

1. 创建一个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对项目的侵入性比较强，可以考虑把注解写在接口上。