swagger实践 及一些踩过的坑

首先就是我们项目中用的swagger2，编辑的时候已经升级到3.0.0了
有空尝试下。
然后至少要是个spring的项目，支持@configuration这个注解的版本，我们项目中用的spring4.1.0。
然后就是开开心心的码代码了

@Configuration  
@EnableWebMvc  
@EnableSwagger2  
@ComponentScan(
        basePackages = {"com.dc.itil"} //swagger扫描的包
    )  
public class Swagger2 {
    @Bean
    ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
        /*      
                "API Title", 
                "API Description", 
                "API Version", 
                "API terms of service",
                "API Contact Email", 
                "API Licence Type", 
                "API License URL");  */
        "ITIL3 API doc",
        "",
        "1.0",
        "",
        "",
        "",
        "" );
        return apiInfo;
    }

    @Bean
    public Docket customImplementation(){
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo());
    }
}

写好了配置类，需要加入一个展示api的页面， swagger UI 这个很好用

看一下目录结构，放在webapp下面，当然我这个是个maven项目
之后就是在接口上加上你的api描述了

启动项目，访问 doc文件夹 ，这时候出来的只是swagger的页面 ，啥也没有

只需要在这里键入你的api数据地址就能找到。当然你也可以让他初始化的时候就显示，这样更方便。
修改index.html中的，换成自己的

 window.swaggerUi = new SwaggerUi({
        url: url,

这样就可以完美优雅的查看接口文档，你之前写的乱七八糟的接口命名也会清晰的暴露出来。

坑：
1. 首先就是我写完配置类Swagger2 .java 之后，访问doc是可以访问的 就是出不来接口文档，这个时候千万不能着急，仔细思考，我一看文档里面标题也没出来，我猜想是@configuration修饰的类没起作用，果然在扫描包路径中没有添加
2. 当点击try it out之后发现访问的路径不对，这时候我审查元素了那个按钮，发现baseURI有问题，这时候需要修改swagger-ui.js中的basepath为自己的项目后端接口路径

this.basePath = response.basePath + "/api"|| '';

总结一下，这个真的很好用，尤其是前后端分离的项目，再也不用给前端大姐写复杂接口文档了，再也不用为接口稳当改来改去费劲了