spring mvc 集成 swagger 详细实践，绝壁原创，耳目一新的感觉。

一般都是在已经很完善的项目里面，去集成这个 swagger ，我这就反其道而行之，仔细看看这个 swagger 到底都依赖些什么jar包。

让你好好了解下这个东西，出了些问题的话，也可以简单的处理下。

我这就是以一个非常简单的 maven hello world 项目的基础上，去集成这个 swagger 的实践记录。

所以，你这得有个如上的简单项目。

我这有以前的链接，可以供小白们参考。

先是创建个简单的hello world 的 maven web项目，参见下面的链接。

IntelliJ IDEA 创建 hello world Java web Maven项目从头到尾都有图有真相2017版本

然后就是在上面的简单项目里面加上spring mvc 相关的东西。参见下面的链接。

Java springmvc web项目，基于maven的hello world入门级项目使用IntelliJ IDEA 2017版本

上面的2个链接都仔细实践过之后，准备工作就OK啦。

开始，怎么集成这个 swagger 

先是pom.xml的 dependency 依赖的添加。

为了一览全貌，我就把全部的依赖放这了，因为是个超简单的项目，所以这个依赖很少，方便观众，看清楚，每个依赖都是干啥的。

<dependencies>
<!-- Spring MVC support -->
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>4.1.4.RELEASE</version>
</dependency>
<!--JSTL-->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jstl</artifactId>
<version>1.2</version>
<scope>runtime</scope>
</dependency>
<!-- swagger2 核心依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<!-- swagger-ui 为项目提供api展示及测试的界面 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<!-- 集成 swagger 的时候，缺少这个 jar包是不OK的-->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.2.3</version>
</dependency>

</dependencies>

我看有的老铁的文章里面，信誓旦旦的说，老简单啦，就需要特别引入 springfox-swagger2 和springfox-swagger-ui  2个jar依赖，就是前面的两个，没有我这个地方的第三个。

也许他不是，从一个完全干净的项目开始整的，搞不好，他的那个项目里面已经有了我上面提供的第三个的依赖。

如果，你觉得湿胸我说的有问题，可以实验一把，把我后面的那个依赖删除了，测试一下。就会发现，index页面跑起来没问题，但是访问咱自己写的controller的时候，就炸啦。我这有如下的报错图，供各位参考。



可以看到是少了个这，

然后再给各位观众看看，当添加上刚刚的三个依赖后，整个项目的各个jar包的依赖关系图。



注意啦，有些老铁嫌弃湿胸的这个图上面的字太小啦，唉，这能怪我吗。。。

你可以，按我下图操作，在新标签页，打开这个图，估计可以看到大图啦。



这下就可以看到整个spring mvc 项目里面的各个jar包的依赖关系啦。

要是还嫌弃小，老铁，你down下来，不就可以放大看了吗？

是不是有耳目一新的感觉，估计以前谁的文章，都没这么直观的告诉你，一个项目的jar包之间的依赖关系是这么来的吧。

想知道上面的这个依赖关系图怎么来的吗？

Intellij IDEA 中如何查看maven项目中所有jar包的依赖关系图
然后就是 spring-servlet.xml

需要添加一句

<mvc:default-servlet-handler />

为了明了的展示问题，我这就把我的全部贴出来。

<?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:mvc="http://www.springframework.org/schema/mvc"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> 
<!-- 开启spring的扫描注入，使用如下注解 -->
<!-- @Component,@Repository,@Service,@Controller-->
<context:component-scan base-package="com.lxk"/>

<!-- 开启springMVC的注解驱动，使得url可以映射到对应的controller -->
<mvc:annotation-driven />
<mvc:default-servlet-handler />
<!-- 视图解析 -->
<bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<property name="prefix" value="/WEB-INF/views/"/>
<property name="suffix" value=".jsp"/>
</bean>

</beans>

里面就是spring mvc 项目相关的一些配置，外加这个插件需要的一个配置。

有些老铁说，要是项目配置了拦截器，需要添加如下的一些配置，

<mvc:exclude-mapping path="/swagger*/**"/>
<mvc:exclude-mapping path="/v2/**"/>
<mvc:exclude-mapping path="/webjars/**"/>

但是我这配置了拦截器，但是，不配置这个，页面也是OK的，所以，这个估计得看个人情况啦。



我注释掉，页面照样可以OK。

最后，就是Java代码的实际操作啦。分2部分，一个是Java不分的配置，一个是实际你需要完善的 那些个信息。

package com.lxk.utils;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* @author lxk on 2017/12/18
*/
@Configuration
@EnableSwagger2
@EnableWebMvc
public class ApiConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.build()
.apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("大师兄集成swagger的接口测试")
.description("闻道有先后，术业有专攻。")
.termsOfServiceUrl("http://blog.csdn.net/qq_27093465?viewmode=contents")
.contact(new Contact("csdn大师兄", "http://blog.csdn.net/qq_27093465", "cmshome@163.com"))
.license("")
.licenseUrl("")
.version("1.0.0")
.build();
}

}

这里面的各个描述和最后的页面的对应关系，一会看运行结果图就知道啦。

最最后，就是在controller里面的请求上使用注解，完善最后的结果图。

package com.lxk.controller;

import com.lxk.model.Student;
import com.lxk.service.StudentService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.ModelAndView;

import javax.annotation.Resource;

/**
* Created by lxk on 2017/3/27
*/
@Controller
@RequestMapping("student")
public class StudentController {

@Resource(name = "studentService")
private StudentService studentService;

//@ResponseBody//(之前我因为加了这个注解，导致页面访问一直是406错误，注释了就好啦，具体为啥我暂时还不知道)
@ApiOperation(value = "获得所有的学生对象list", notes = "get请求，查询所有的学生。")
@RequestMapping(value = "/getAllStudent", method = RequestMethod.GET)
public ModelAndView getAllStudent() {
ModelAndView mav = new ModelAndView();
mav.setViewName("studentDisplay");
mav.addObject("students", studentService.getAllStudent());
return mav;
}

@ApiOperation(value = "根据学生的name，获得单个学生的信息", notes = "根据学生的name，查询学生对象的信息。")
@ApiImplicitParam(name = "name", value = "学生的名称", required = true, dataType = "String")
@ResponseBody
@RequestMapping(value = "getStudentByName", method = RequestMethod.POST)
public String getStudentByName(String name) {
return "";
}

@ApiOperation(value = "根据学生的name和age，获得单个学生的信息", notes = "根据学生的name和age，查询学生对象的信息。")
@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "学生名称", required = true, dataType = "String"),
@ApiImplicitParam(name = "age", value = "学生年龄", required = true, dataType = "int")})
@ResponseBody
@RequestMapping(value = "getStudentByNameAndAge", method = RequestMethod.POST)
public String getStudentByName(String name, int age) {
return "";
}

@ApiOperation(value = "新建学生对象到数据库", notes = "新建数据到数据库。")
@ApiImplicitParam(name = "student", value = "学生对象", required = true, dataType = "Student")
@ResponseBody
@RequestMapping(value = "createNewStudent", method = RequestMethod.POST)
public String create(@RequestBody Student student) {
return "";
}
}

一切OK，之后，配置好tomcat，然后启动服务器，然后，跳转到index页面，然后，就打开页面的链接；
http://localhost:8080/lxk/swagger-ui.html#/
这地方的lxk，是我配置tomcat的时候给配置上去的，各位因地制宜哦。

然后就是运行结果图。



这就是最终的执行结果。

图上的箭头，就是刚刚在Java代码里面2个地方写的信息。

还有啊，这几个请求是可以点开的，里面还有详情呢。老铁们实践的时候，可以点开看看。我就不截图啦。

至此，这个集成的实践，就算完啦。

说下感想：

这个东西，也不是很好呀，只是说，作为开发者，你省却了去写开发文档的时间，但是这个页面出来之后，并不是很好用。而且，你在controller里面加的那些个注解，以及注解上使用的参数，也就是你写的那些个描述信息，这都是和代码的逻辑没什么关系的，用高级点的术语，就是这个非常的入侵，非常的不友好。我们这也是说领导要让我们开发写开发文档，有什么请求，请求的参数，都返回什么，都是干啥的，都是什么请求方式等等这些信息。因为这个文档的书写和维护很麻烦的，所以，打算使用这个 swagger 插件来简化这个 工作。但是，我觉得这东西并不好啊。非常不好。我个人是这么觉得的。

我写完文章，给自己点个赞，不过分吧，

不过分，那我可就点啦啊。

我先点为敬，你们随意。大家随意。不要客气。。。

想要源码吗？

不免费送啦，你懂的。

听说有些老铁，要感谢下大师兄？扫一扫，领红包啦。顺便表示一下，怎么样？