搜索
您的当前位置：首页正文

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 
    
    
     
     
         
         
          ">

    <!-- 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资源包的下载地址啦~

Copyright © 2019- yule263.com 版权所有
湘ICP备2023023988号-1

Top