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的自己添加：
        <!-- AOP合成字节码的实现框架 -->
        <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjrt</artifactId>
            <version>1.7.3</version>
        </dependency>
        <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjweaver</artifactId>
            <version>1.7.3</version>
            <scope>runtime</scope>
        </dependency>
        <!-- Spring AOP模块 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-aop</artifactId>
            <version>4.2.5.RELEASE</version>
        </dependency>
        <!-- JSON处理框架 -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.5.4</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.5.4</version>
        </dependency>
        <!-- Swagger依赖 -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <scope>compile</scope>
            <version>1.5.3</version>
            <exclusions>
                <exclusion>
                    <groupId>javax.ws.rs</groupId>
                    <artifactId>jsr311-api</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
  1. 然后是maven插件配置，顺便把jetty和打包插件也列出
    <build>
        <finalName>doc-searcher-web</finalName>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
        <plugins>
            <!-- jetty插件 -->
            <plugin>
                <groupId>org.mortbay.jetty</groupId>
                <artifactId>maven-jetty-plugin</artifactId>
                <version>6.1.20</version>
                <configuration>
                    <connectors>
                        <connector implementation="org.mortbay.jetty.nio.SelectChannelConnector">
                            <port>8080</port>
                            <maxIdleTime>60000</maxIdleTime>
                        </connector>
                    </connectors>
                    <contextPath>/doc-searcher-web</contextPath>
                    <systemProperties>
                        <systemProperty>
                            <name>org.mortbay.jetty.Request.maxFormContentSize</name>
                            <value>-1</value>
                        </systemProperty>
                    </systemProperties>
                </configuration>
            </plugin>
            <!-- maven编译插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.2</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <!-- maven资源插件，作用于maven的resources目录下 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <version>2.7</version>
                <configuration>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <!-- maven war包打包插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.2</version>
                <configuration>
                    <warName>${project.artifactId}</warName>
                </configuration>
            </plugin>
            <!-- 重点：swagger插件 -->
            <plugin>
                <groupId>com.github.kongchen</groupId>
                <artifactId>swagger-maven-plugin</artifactId>
                <version>3.1.0</version>
                <configuration>
                    <apiSources>
                        <apiSource>
                            <!-- 支持springMVC -->
                            <springmvc>true</springmvc>
                           <!-- 你的web项目Controller包名 --> <locations>cn.coselding.docsearcher.web.controller</locations>
                           <!-- 协议 -->
                            <schemes>http</schemes>
                            <!-- 所在主机，可以为空 -->
                            <host>localhost:8080</host>
                            <!-- web项目Context Path -->
                            <basePath>/doc-searcher-web</basePath>
                            <!-- 必须！要在主页显示你的API的整体信息的，相当于是标题 -->
                            <info>
                                <title>文档搜索器</title>
                                <version>v1</version>
                                <description>
                                    文档搜索器-API
                                </description>
                            </info>
                           <!-- 模板位置，支持classpath:类型路径 --> <templatePath>classpath:/template/markdown.hbs</templatePath>
                           <!-- 编译期扫描controller之后合成的API文档输出位置 --> <outputPath>${project.basedir}/src/main/webapp/swagger-ui/document.md</outputPath>
                           <!-- web目录下的js、css等资源位置 --> <swaggerDirectory>${project.basedir}/src/main/webapp/swagger-ui/</swaggerDirectory>
                        </apiSource>
                    </apiSources>
                </configuration>
                <!-- 这里很重要，简单说就是配置在maven的compile生命周期执行时触发swagger插件的generate命令 -->
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

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

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


    webapp-resources.png

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


    classpath-resources.png

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

  3. SpringMVC配置

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:context="http://www.springframework.org/schema/context"
    xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:aop="http://www.springframework.org/schema/aop"
    xsi:schemaLocation="http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.2.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.2.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.2.xsd
        http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd ">

    <!-- Controller包扫描 -->
    <context:component-scan base-package="cn.coselding.docsearcher.web.controller"/>

    <!-- springMVC注解驱动支持 -->
    <mvc:annotation-driven/>

    <!-- 容器默认的DefaultServletHandler处理 所有静态内容与无RequestMapping处理的URL，不设置这个你在请求刚才的js、css文件就请求不到了 -->
    <mvc:default-servlet-handler/>

    <!-- 声明swagger资源文件位置，表示这个路径下的SpringMVC的DispatcherServlet不拦截 -->
    <mvc:resources mapping="/swagger-ui/**" location="/swagger-ui/"/>
    <!-- SpringMVC设置AOP -->
    <aop:aspectj-autoproxy expose-proxy="true" proxy-target-class="false"/>
</beans>

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

  1. 上面那些是整体环境配置，接下来只要在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<String, Object> 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，不然会报错~如下：
    <mvc:interceptors>
        <!-- Jobs鉴权拦截器 -->
        <mvc:interceptor>
            <mvc:mapping path="/**/*"/>
            <!-- 排除对swagger-ui目录下的拦截 -->
            <mvc:exclude-mapping path="/swagger-ui/**"/>
            <bean class="com.weidian.jobs.web.interceptor.JobsAuthInterceptor">
            </bean>
        </mvc:interceptor>
    </mvc:interceptors>
  1. 文首，我的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<String, Object> result = new HashMap<>();
        result.put("result", "success");
        result.put("id", id);
        return result;
    }

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

相关博客

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

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 158,847评论 4赞 362
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 67,208评论 1赞 292
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 108,587评论 0赞 243
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 43,942评论 0赞 205
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 52,332评论 3赞 287
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 40,587评论 1赞 218
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 31,853评论 2赞 312
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 30,568评论 0赞 198
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 34,273评论 1赞 242
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 30,542评论 2赞 246
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 32,033评论 1赞 260
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 28,373评论 2赞 253
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 33,031评论 3赞 236
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 26,073评论 0赞 8
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,830评论 0赞 195
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 35,628评论 2赞 274
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 35,537评论 2赞 269

推荐阅读更多精彩内容