cxf-restful的一个非常好用的接口文档测试工具

一、 Swagger-ui 是什么

  参照：http://www.cnblogs.com/youxin/p/3995016.html

二、下载swagger-ui

  1.swagger在github上托管的项目代码： https://github.com/wordnik/swagger-ui 

  2.下载后将dist目录下的所有文件copy到项目的webapp目录下

  3.此时启动项目后访问http:ip:port/project/index.html便会出现以下界面

                        

  1.这个访问的是swagger-ui 的demo, 我们是需要用它来访问我们自己的项目，所以我们做以下修改：

        a) 将index.html修改成index.jsp；具体名称根据需要修改，有些时候可能index.jsp已经被使用，或者index.jsp被拦截器拦截就需要使用其他的名称了，

        b) 修改index.jsp让文档访问我们项目的路径，具体修改如下图：

其中URL中的priject就是项目的访问地址，如我的项目的restful接口地址是：http://127.0.0.1:8080/mytest/service/rest/{具体的实现接口}那么我的URL就是${ctx}/mytest/service/rest/api-docs

三、代码添加注解，生成文档

  1. 添加maven依赖

        <dependency>
            <groupId>com.wordnik</groupId>
            <artifactId>swagger-jaxrs_2.10</artifactId>
            <version>1.3.12</version>
        </dependency>

    2.applicationContext.xml中添加配置

    <bean id="swaggerResourceJSON" class="com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON" />
    <bean id="resourceWriter" class="com.wordnik.swagger.jaxrs.listing.ResourceListingProvider" />
    <bean id="apiWriter" class="com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider" />

   <jaxrs:server address="/rest"  id="swagger">
       <jaxrs:serviceBeans>
          <list>
    <!--api文档接口 start-->
              <ref  bean = "swaggerResourceJSON" />
    <!--api文档接口  end -->
           </list>
       </jaxrs:serviceBeans>
       <jaxrs:providers>
           <ref bean="resourceWriter" />
            <ref bean="apiWriter" />
       </jaxrs:providers>
</jaxrs:server>
<!-- 下面这一段配置一定要放在以上配置的后面，否则无法正常生成 -->
     <!-- this scans the classes for resources -->
    <bean id="swaggerConfig" class="com.wordnik.swagger.jaxrs.config.BeanConfig">
      <property name="resourcePackage" value="文档自动扫描报名配置"/>
      <property name="version" value="${wjbz.api.version}"/>
      <property name="basePath" value="项目的根路径"/>
      <property name="title" value="XXX接口测试文档"/>
      <property name="description" value="项目说明，显示在文档的最上面"/>
      <property name="contact" value="contact"/>
      <property name="license" value="${wjbz.api.license}"/>
      <property name="licenseUrl" value="${wjbz.api.license_url}"/>
      <property name="scan" value="true"/>
    </bean>

   3.  接口定义类中添加注解，生成文档

@Path("/apiTest")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@Api(value = "/apiTest", description = "swagger-ui文档集成测试")
public interface IApiTestRest {
    
    @GET
    @Path("/someThing/{id}")
    @ApiOperation(value = "get方式获取某些信息")
    public void getSomeThing( @ApiParam("某些信息的id") @PathParam("id") String id);
    
    @POST
    @Path("/getUser")
    @ApiOperation(value = "获取用户信息", response = User.class)
    public User getUser(UserParams queryParams);

}

@ApiModel("用户信息")
 public class User{
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "id", required = true)
    private String id;

    public String getName() {
        return name;
    }

    public String getId() {
        return id;
    }

    public void setName(String name) {
        this.name = name;
    }

    public void setId(String id) {
        this.id = id;
    }
    
}
@ApiModel("用户参数说明")
44 @JsonIgnoreProperties(ignoreUnknown = true)
public class UserParams{
    @ApiModelProperty(value="姓名",required = true)
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
    
}

  5.注意：

 

如上图中response定义的是返回值类型，如果在返回值中注解添加不完整则可能出现生成后的文档中没有相关字段介绍，也有可能出现错误，导致文档无法解析，如若返回值类型不能添加注解（如：map<String, String>）,建议用String.Class代替或去除该属性。

如此，swagger-ui已经集成好了

 

小白一只，第一次发帖，还请各位大神多指教