SpringBoot学习笔记之集成swagger

集成步骤

1、在pom.xml中引用度swagger依赖包

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.6.1</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.6.1</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-core</artifactId>

<version>2.6.5</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-databind</artifactId>

<version>2.6.5</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-annotations</artifactId>

<version>2.6.5</version>

</dependency>

2、创建swager配置类

package com.vk.liyj.config;

import io.swagger.annotations.ApiOperation;

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.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

* 类描述：配置swagger2信息

*/

@Configuration // 让Spring来加载该类配置

//@EnableWebMvc // 启用Mvc，非springboot框架需要引入注解@EnableWebMvc

@EnableSwagger2 // 启用Swagger2

public class Swagger2Config {

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

// 扫描指定包中的swagger注解

// .apis(RequestHandlerSelectors.basePackage("com.vk.liyj"))

// 扫描所有有注解的api，用这种方式更灵活

.apis(RequestHandlerSelectors

.withMethodAnnotation(ApiOperation.class))

.paths(PathSelectors.any()).build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("基础平台 RESTful APIs")

.description(

"基础平台 RESTful 风格的接口文档，内容详细，极大的减少了前后端的沟通成本，同时确保代码与文档保持高度一致，极大的减少维护文档的时间。")

.termsOfServiceUrl("http://xiachengwei5.coding.me")

.contact("Xia").version("1.0.0").build();

}

}

通过@Configuration注解，表明它是一个配置类，@EnableSwagger2开启swagger2。apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。

3、编写swagger注解

package com.vk.liyj.model;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

import java.util.Date;

import org.springframework.format.annotation.DateTimeFormat;

import com.fasterxml.jackson.annotation.JsonFormat;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

import com.fasterxml.jackson.annotation.JsonInclude;

/**

* 人员信息表 注解：@ApiModel 和 @ApiModelProperty 用于在通过对象接收参数时在API文档中显示字段的说明

* 注解：@DateTimeFormat 和 @JsonFormat 用于在接收和返回日期格式时将其格式化 实体类对应的数据表为： user_info

*

*

*/

@JsonInclude(JsonInclude.Include.NON_NULL)

@JsonIgnoreProperties({ "handler", "hibernateLazyInitializer" })

@ApiModel(value = "UserInfo")

public class UserInfo {

@ApiModelProperty(value = "ID")

private Integer id;

@ApiModelProperty(value = "用户登录账号", required = true)

private String userNo;

@ApiModelProperty(value = "姓名", required = true)

private String userName;

@ApiModelProperty(value = "姓名拼音")

private String spellName;

@ApiModelProperty(value = "密码", required = true)

private String password;

@ApiModelProperty(value = "手机号", required = true)

private String userPhone;

@ApiModelProperty(value = "性别")

private Integer userGender;

@ApiModelProperty(value = "记录创建时间")

@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")

private Date createTime;

@ApiModelProperty(value = "记录修改时间")

@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")

private Date updateTime;

@JsonFormat(locale = "zh", timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")

public Date getCreateTime() {

return createTime;

}

@JsonFormat(locale = "zh", timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")

public Date getUpdateTime() {

return updateTime;

}

}

4、控制器类

package com.vk.liyj.controller;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

import java.util.List;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.stereotype.Controller;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RequestParam;

import com.vk.liyj.model.UserInfo;

import com.vk.liyj.service.UserInfoService;

/**

* 类描述：人员基本信息

*/

@Controller

@RequestMapping(value = "/userInfo")

@Api(value = "UserInfo", description = "人员基本信息 ")

public class UserInfoController {

@Autowired

UserInfoService service;

@RequestMapping(value = "/selectAllUsers", method = RequestMethod.GET)

@ApiOperation(value = "查询所有的人员信息", notes = "查询所有的人员信息")

public String selectAllUsers(HttpServletRequest request, HttpServletResponse response) {

List<UserInfo> userList = service.selectAllUsers();

request.setAttribute("userList", userList);

return "userList.jsp";

}

@RequestMapping(value = "selectById", method = RequestMethod.GET)

@ApiOperation(value = "根据用户id查询用户详细信息", notes = "根据用户id查询用户详细信息")

@ApiImplicitParams({

@ApiImplicitParam(name = "type", value = "类型（修改：update；默认为查看）", required = false, paramType = "query"),

@ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "query")

})

public String selectById(HttpServletRequest request, HttpServletResponse response,

@RequestParam(value = "id") Integer id, @RequestParam(value = "type") String type) {

UserInfo user = service.selectByPrimaryKey(id);

request.setAttribute("user", user);

if("update".equals(type)) {

return "userUpdate.jsp";

} else {

return "userView.jsp";

}

}

@RequestMapping(value = "deleteById", method = RequestMethod.GET)

@ApiOperation(value = "根据用户id删除用户信息", notes = "根据用户id删除用户信息")

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "query")

})

public String deleteById(HttpServletRequest request, HttpServletResponse response, @RequestParam(value = "id") Integer id) {

int count = 0;

try {

count = service.deleteByPrimaryKey(id);

if(count <=0 ) {

return "error.jsp";

} else {

request.getRequestDispatcher("selectAllUsers").forward(request, response);

return "userList.jsp";

}

} catch (Exception e) {

e.getMessage();

e.printStackTrace();

return "error.jsp";

}

}

@RequestMapping(value = "add", method = RequestMethod.POST)

@ApiOperation(value = "添加用户信息", notes = "添加用户信息")

public String add(HttpServletRequest request, HttpServletResponse response, UserInfo user) {

int count = 0;

try {

count = service.insertSelective(user);

if(count <=0 ) {

return "error.jsp";

} else {

//POST请求的方法不能直接转发到GET请求的方法，需要重定向

response.sendRedirect("selectAllUsers");

return "userList.jsp";

}

} catch (Exception e) {

e.getMessage();

e.printStackTrace();

return "error.jsp";

}

}

@RequestMapping(value = "update", method = RequestMethod.POST)

@ApiOperation(value = "根据用户id修改用户信息", notes = "根据用户id修改用户信息")

public String update(HttpServletRequest request, HttpServletResponse response, UserInfo user) {

int count = 0;

try {

count = service.updateByPrimaryKeySelective(user);

if(count <=0 ) {

return "error.jsp";

} else {

//POST请求的方法不能直接转发到GET请求的方法，需要重定向

response.sendRedirect("selectAllUsers");

return "userList.jsp";

}

} catch (Exception e) {

e.getMessage();

e.printStackTrace();

return "error.jsp";

}

}

}

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiParamImplicitL：一个请求参数
• @ApiParamsImplicit 多个请求参数

5、启动程序访问 http://localhost:8080/spring-mvc/swagger-ui.html

6、替换默认的UI

<dependency>

<groupId>com.github.xiaoymin</groupId>

<artifactId>swagger-bootstrap-ui</artifactId>

<version>1.6</version>

</dependency>

<!-- 使用swagger-bootstrap-ui替换默认的UI

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.6.1</version>

</dependency>

-->

替换后访问路径：http://localhost:8080/web/doc.html

参考资料

http://blog.csdn.net/songanling/article/details/71079304

https://gitee.com/xiaoym/swagger-bootstrap-ui

源码下载地址：http://download.csdn.net/download/liyuejin/9986140