Rest 文件神器 swagger （2）

方健發表於2014-12-18
RESTSwagger

例項程式碼: https://bitbucket.org/fangj/swagger-springmvc-example

主要參考：

http://blog.zenika.com/index.php?post/2013/07/11/Documenting-a-REST-API-with-Swagger-and-Spring-MVC
http://www.3pillarglobal.com/insights/restful-api-documentation-using-swagger-and-spring-mvc

步驟：

  1. 先借一個Spring MVC的工程程式碼 http://www.mkyong.com/spring-mvc/spring-3-rest-hello-world-example/

  2. 修改pom.xml 加入jetty

        <plugin>
        <groupId>org.eclipse.jetty</groupId>
        <artifactId>jetty-maven-plugin</artifactId>
        <version>9.2.2.v20140723</version>
    </plugin>

    mvn jetty:run試下可以跑起來

  3. 加入swagger-springmvc 

    <dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>0.5.2</version>
</dependency>

  4. 在spring的xml中加入 

    <bean class="com.mangofactory.swagger.configuration.DocumentationConfig" />
<context:property-placeholder location="classpath:/swagger.properties" />

  5. 在resouces下面加入swagger.properties，內容如下：

    documentation.services.version=1.0
documentation.services.basePath=http://localhost:8080

  6. 理論上講就OK了。但是似乎我的Spring MVC裡少了些東西，而且如果返回JSON需要JACKSON。所以再從以前的工程裡拷貝一堆到POM。最後POM長這樣： 

    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mkyong.common</groupId>
    <artifactId>SpringMVC</artifactId>
    <packaging>war</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>SpringMVC Maven Webapp</name>
    <url>http://maven.apache.org</url>
    <properties>
        <spring.version>4.0.0.RELEASE</spring.version>
        <slf4j.version>1.6.4</slf4j.version>
        <junit.version>4.11</junit.version>
        <jackson.version>1.9.10</jackson.version>
    </properties>
    <dependencies>
        <!-- Spring 3 dependencies -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
            <version>${spring.version}</version>
            <exclusions>
                <exclusion>
                    <artifactId>commons-logging</artifactId>
                    <groupId>commons-logging</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
            <version>4.0.0.RELEASE</version>
            <exclusions>
                <exclusion>
                    <artifactId>commons-logging</artifactId>
                    <groupId>commons-logging</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-web</artifactId>
            <version>${spring.version}</version>
            <exclusions>
                <exclusion>
                    <artifactId>commons-logging</artifactId>
                    <groupId>commons-logging</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
            <version>${spring.version}</version>
            <exclusions>
                <exclusion>
                    <artifactId>commons-logging</artifactId>
                    <groupId>commons-logging</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <!--slf4j-->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>jcl-over-slf4j</artifactId>
            <version>${slf4j.version}</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>${slf4j.version}</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
            <version>${slf4j.version}</version>
        </dependency>
        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>1.2.14</version>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.5</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.codehaus.jackson</groupId>
            <artifactId>jackson-mapper-asl</artifactId>
            <version>1.9.13</version>
        </dependency>
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>0.5.2</version>
        </dependency>
    </dependencies>
    <build>
        <finalName>SpringMVC</finalName>
        <plugins>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.eclipse.jetty</groupId>
                <artifactId>jetty-maven-plugin</artifactId>
                <version>9.2.2.v20140723</version>
            </plugin>
        </plugins>
    </build>
</project>

  7. mvn jetty:run跑下。訪問 http://localhost:8080/api-docs/ 可以看到文件描述了。

  8. 此時伺服器端的任務已經完成。但是最好玩的在後面。從https://github.com/swagger-api/swagger-ui上下載程式碼。拷貝其中dist目錄中的部分出來。到webapp/static/swagger目錄

  9. 在spring的xml中加入這一句把靜態資源目錄暴露出來

    <mvc:resources mapping="/static/**" location="/static/"/>
  10. 對swagger/index.html做點小修改。把googlefonts那行刪了,國內忒慢。把"url=..."那行改為上面的地址url = "http://localhost:8080/api-docs";
  11. 在執行下mvn jetty:run 訪問 http://localhost:8080/static/swagger/index.html#!/movie/getMovie 可以看到 swagger-ui

    收工！

======= 更新 ======

如使用1.0.2版本的springmvc

<dependency>
  <groupId>com.mangofactory</groupId>
  <artifactId>swagger-springmvc</artifactId>
  <version>1.0.2</version>
</dependency>

需加入

<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

相關文章