restful文档神器 swagger (2)

主要参考：

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.0documentation.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 可以看到 [+]查看原图

    收工！

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

如使用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" />