Swagger maven plugin 环境配置踩坑记录

症状

按照该有的教程都配置完成了，swagger页面也正常显示，但是呢，页面里面一个API也没有，关键是我明明按照该有的步骤配置好了相关的注解了，如下图：

api-list-empty.png

列表里面一条也木有啊。。。

Swagger环境搭建

• 强行插入一下，不说说环境搭建你可能都对我说的东西一脸蒙蔽哈哈哈~

• Swagger是一个很方便的合成API文档的工具，有了它，你只要专心做API接口就行了，接口文档Swagger帮你完成，毕竟写完代码之后一想到还要给App或者H5团队一个个讲自己的接口该怎么用，实在是很心累，有了Swagger，只要你的接口开发完毕，部署到测试服务器，只要把swagger页面链接扔给他们就行了~ 多爽~

我这里使用maven的插件方式在项目中接入Swagger，项目使用SpringMVC

1. maven依赖，列出swagger使用的相关依赖，其他Spring和SpringMVC的自己添加：

        
        
            org.aspectj
            aspectjrt
            1.7.3
        
        
            org.aspectj
            aspectjweaver
            1.7.3
            runtime
        
        
        
            org.springframework
            spring-aop
            4.2.5.RELEASE
        
        
        
            com.fasterxml.jackson.core
            jackson-core
            2.5.4
        
        
            com.fasterxml.jackson.core
            jackson-databind
            2.5.4
        
        
        
            io.swagger
            swagger-core
            compile
            1.5.3
            
                
                    javax.ws.rs
                    jsr311-api
                
            
        

2. 然后是maven插件配置，顺便把jetty和打包插件也列出

    
        doc-searcher-web
        
            
                src/main/resources
                true
            
        
        
            
            
                org.mortbay.jetty
                maven-jetty-plugin
                6.1.20
                
                    
                        
                            8080
                            60000
                        
                    
                    /doc-searcher-web
                    
                        
                            org.mortbay.jetty.Request.maxFormContentSize
                            -1
                        
                    
                
            
            
            
                org.apache.maven.plugins
                maven-compiler-plugin
                3.2
                
                    1.8
                    1.8
                    UTF-8
                
            
            
            
                org.apache.maven.plugins
                maven-resources-plugin
                2.7
                
                    UTF-8
                
            
            
            
                org.apache.maven.plugins
                maven-war-plugin
                2.2
                
                    ${project.artifactId}
                
            
            
            
                com.github.kongchen
                swagger-maven-plugin
                3.1.0
                
                    
                        
                            
                            true
                            cn.coselding.docsearcher.web.controller
                           
                            http
                            
                            localhost:8080
                            
                            /doc-searcher-web
                            
                            
                                
                                v1
                                
                                    文档搜索器-API
                                
                            
                            classpath:/template/markdown.hbs
                            ${project.basedir}/src/main/webapp/swagger-ui/document.md
                            ${project.basedir}/src/main/webapp/swagger-ui/
                        
                    
                
                
                
                    
                        compile
                        
                            generate
                        
                    
                
            
        
    

很好理解，在maven的compile生命周期触发的时候触发swagger的generate命令，当然你直接使用插件的generate手动执行也可以，执行完成之后会在webapp/swagger-ui/目录下生成swagger.json里面就列出了扫描到的所有接口信息。

3. webapp目录下放入资源文件，是一些css、js、html之类的文件，如下图：

   
   
   

   webapp-resources.png

4. classpath下放入一些模板资源文件，如下图：

   
   
   

   classpath-resources.png
   
   

   以上这两个资源包是公司一个大佬@张章改过的，网上没找到，最后会给出几个博客，也能拿到相关的资源，不过是官方原生的。

5. SpringMVC配置

这里主要就是配置这个AOP，它会在编译期拦截读取各个Controller的注解接口信息，提取关键数据，合成swagger.json文件，有了这个文件，剩下那些html就能渲染出相关的接口文档页面。

6. 上面那些是整体环境配置，接下来只要在Controller编写的时候加点注解，文档就帮你合成好啦~
   注解使用：如下一个样例Controller：

/**
 * @author linyuqiang
 * @version 1.0.0 2017/4/4
 */
@Controller
@RequestMapping("/test")
@Api("文档搜索器API")
public class UrlCatcherController {

    @ApiOperation("测试1")
    @RequestMapping(value = "/spider/{id}", method = RequestMethod.POST)
    @ResponseBody
    public Map spider(
            @ApiParam(required = true,name = "id",value = "测试id")
            @PathVariable("id") Integer id) {
        Map result = new HashMap<>();
        result.put("result", "success");
        result.put("id", id);
        return result;
    }
}

• @Api("文档搜索器API")：这个是整个Controller的标题，Controller下的所有接口会被整理在同一个列表组下，组名组名就是这个。
• @ApiOperation("测试1")：这个是具体的一个接口的名称
• @ApiParam(required = true,name = "id",value = "测试id")：这个是接口参数的标注，required不用说，name标注作用的表单参数名称，和下面的id对应，value是文档页面上这个参数的描述

之后，maven jetty启动项目，访问页面http://localhost:8080/doc-searcher-web/swagger-ui/index.html，如下图所示：

swagger-show.png

还能在参数那边输入对应的值，直接测试接口呢~

踩坑记录

1. 如果你设置了SpringMVC拦截器，要注意，必须对webapp/swagger-ui/目录下的exclude，不然会报错~如下：

2. 文首，我的Swagger页面居然没有API列表是为什么？如下是我之前的Controller方法注解：

    @ApiOperation("测试1")
    @RequestMapping(value = "/spider/{id}")
    @ResponseBody
    public Map spider(
            @ApiParam(required = true,name = "id",value = "测试id")
            @PathVariable("id") Integer id) {
        Map result = new HashMap<>();
        result.put("result", "success");
        result.put("id", id);
        return result;
    }

对，就是没method = RequestMethod.POST参数，你这边写了什么参数，Swagger就给你在API列表相应添加一条，没写就什么都没有，这个错误我犯了两次了，真不能忍啊！！！

相关博客

末尾，来几个搭建教程，里面就有相关的swagger资源包的下载地址啦~

• 利用Swagger Maven Plugin生成Rest API文档
• swagger-ui开源地址
• swagger-maven-plugin开源地址