使用springfox 集成swagger 與spring mvc

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對項目的侵入性比較強，能夠考慮把註解寫在接口上。