Swagger介绍
OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格 式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在github上。 (https://github.com/OAI/OpenAPI-Specification) Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周 期的开发。 (https://swagger.io/) Spring Boot 可以集成Swagger,生成Swagger接口,Spring Boot是Java领域的神器,它是Spring项目下快速构建 项目的框架。
Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口,常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对 象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用 该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
@ApiImplicitParam属性:
添加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>
创建swagger配置类:
package com.xuecheng.api.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
//
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//这种方式可以试一下
//.apis(RequestHandlerSelectors.basePackage("com.xuecheng.manage_cms.controller"))
//扫描所有有注解的api,用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试swagger")
.description("api文档")
// .termsOfServiceUrl("/")
.version("1.0")
.build();
}
}
编写swagger接口注解
package com.swagger.test;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
@Api(value="cms页面管理接口",description = "cms页面管理接口,提供页面的增、删、改、查")
public interface CmsPageControllerApi {
final String API_PRE = "/cms/page";
@GetMapping(API_PRE+"/list/{page}/{size}")
@ApiOperation("分页查询页面列表")
@ApiImplicitParams({
@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="integer"),
@ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="integer")
})
public QueryResponseResult findList(@PathVariable("page") int page, @PathVariable("size") int size, QueryPageRequest queryPageRequest) ;
}
package com.xia.model;
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;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* 人员信息表
* 注解:@ApiModel 和 @ApiModelProperty 用于在通过对象接收参数时在API文档中显示字段的说明
* 注解:@DateTimeFormat 和 @JsonFormat 用于在接收和返回日期格式时将其格式化
* 实体类对应的数据表为: user_info
* @author XiaChengwei
* @date: 2017-07-14 16:45:29
*/
@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;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getUserNo() {
return userNo;
}
public void setUserNo(String userNo) {
this.userNo = userNo == null ? null : userNo.trim();
}
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName == null ? null : userName.trim();
}
public String getSpellName() {
return spellName;
}
public void setSpellName(String spellName) {
this.spellName = spellName;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password == null ? null : password.trim();
}
public String getUserPhone() {
return userPhone;
}
public void setUserPhone(String userPhone) {
this.userPhone = userPhone == null ? null : userPhone.trim();
}
public Integer getUserGender() {
return userGender;
}
public void setUserGender(Integer userGender) {
this.userGender = userGender;
}
@JsonFormat(locale = "zh", timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")
public Date getCreateTime() {
return createTime;
}
public void setCreateTime(Date createTime) {
this.createTime = createTime;
}
@JsonFormat(locale = "zh", timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")
public Date getUpdateTime() {
return updateTime;
}
public void setUpdateTime(Date updateTime) {
this.updateTime = updateTime;
}
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append(getClass().getSimpleName());
sb.append(" [");
sb.append("Hash = ").append(hashCode());
sb.append(", id=").append(id);
sb.append(", userNo=").append(userNo);
sb.append(", userName=").append(userName);
sb.append(", spellName=").append(spellName);
sb.append(", password=").append(password);
sb.append(", userPhone=").append(userPhone);
sb.append(", userGender=").append(userGender);
sb.append(", createTime=").append(createTime);
sb.append(", updateTime=").append(updateTime);
sb.append("]");
return sb.toString();
}
}
这个转载自:[springmvc集成swagger](https://segmentfault.com/a/1190000010554445)
package com.infore.controller;
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.bind.annotation.RestController;
import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;
import com.infore.common.pinyin.PinyinUtils;
import com.infore.common.util.ControllerUtil;
import com.infore.model.ResponseDto;
import com.infore.model.UserInfo;
import com.infore.model.dto.UserInfoDto;
import com.infore.service.UserInfoService;
import gbap.log.Logger;
import gbap.log.LoggerFactory;
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.annotation.Resource;
import javax.ws.rs.core.MediaType;
/**
* 人员信息控制类
* @author XiaChengwei
* @date: 2017-07-14 16:45:29
*/
@RestController
@RequestMapping(value = "/userInfo", produces = MediaType.APPLICATION_JSON)
@Api(value = "用户信息", description = "用户信息", produces = MediaType.APPLICATION_JSON)
public class UserInfoController {
private Logger logger = LoggerFactory.getLogger(getClass());
@Resource
UserInfoService service;
@ResponseBody
@RequestMapping(value = "/selectAllUsers", method = RequestMethod.GET)
@ApiOperation(value = "查询所有的人员信息并分页展示", notes = "查询所有的人员信息并分页展示")
@ApiImplicitParams({
@ApiImplicitParam(name = "page",value = "跳转到的页数", required = true, paramType = "query"),
@ApiImplicitParam(name = "size",value = "每页展示的记录数", required = true, paramType = "query")
})
public ResponseDto selectAllUsers(Integer page, Integer size) {
page = page == null || page <= 0 ? 1 : page;
size = size == null || size <= 5 ? 5 : size;
PageHelper.startPage(page, size);//PageHelper只对紧跟着的第一个SQL语句起作用
List<UserInfo> userInfoList = service.selectAllUsers();
PageInfo pageInfo = new PageInfo(userInfoList);
return ControllerUtil.returnDto(true, "成功", pageInfo);
}
@ResponseBody
@RequestMapping(value = "/selectContacts", method = RequestMethod.GET)
@ApiOperation(value = "查询通讯录人员信息", notes = "查询通讯录人员信息")
public ResponseDto selectContacts() {
List<UserInfo> list = service.selectContacts();
return ControllerUtil.returnDto(true, "成功", list);
}
@ResponseBody
@RequestMapping(value = "selectByUserNo", method = RequestMethod.GET)
@ApiOperation(value = "新增人员前先检测用户名是否可用", notes = "新增人员前先检测用户名是否可用")
@ApiImplicitParams({
@ApiImplicitParam(name = "user_no", value = "用户输入的用户名", required = true, paramType = "query")
})
public ResponseDto selectByUserNo(String user_no) {
UserInfo userInfo = service.selectByUserNo(user_no);
if(null == userInfo || "".equals(userInfo.getUserNo())) {
return ControllerUtil.returnDto(true, "此用户名可用", null);
}else {
return ControllerUtil.returnDto(false, "此用户名不可用", null);
}
}
@ResponseBody
@RequestMapping(value = "insertSelective", method = RequestMethod.POST)
@ApiOperation(value = "新增人员", notes = "新增人员")
public ResponseDto insertSelective(UserInfoDto userInfoDto) {
int count = 0;
PinyinUtils pinyin = new PinyinUtils();
try {
//新增人员之前先检查用户名是否可用
UserInfo userInfo = service.selectByUserNo(userInfoDto.getUserNo());
if(null != userInfo && !"".equals(userInfo.getUserNo())) {
return ControllerUtil.returnDto(false, "此用户名不可用", null);
}
if(null != userInfoDto.getUserName() && !"".equals(userInfoDto.getUserName())) {
//获取姓名拼音并存在对象中
userInfoDto.setSpellName(pinyin.getPingYin(userInfoDto.getUserName()));
}else {
return ControllerUtil.returnDto(false, "请输入姓名", count);
}
count = service.insertSelective(userInfoDto);
if(count <= 0) {
return ControllerUtil.returnDto(false, "失败", count);
}else {
return ControllerUtil.returnDto(true, "成功", count);
}
} catch (Exception e) {
logger.error("userInfo--insertSelective:系统异常");
return ControllerUtil.returnDto(false, "系统异常", count);
}
}
@ResponseBody
@RequestMapping(value = "updateByPrimaryKeySelective", method = RequestMethod.POST)
@ApiOperation(value = "根据id修改人员信息", notes = "根据id修改人员信息")
public ResponseDto updateByPrimaryKeySelective(UserInfoDto userInfoDto) {
int count = 0;
try {
count = service.updateByPrimaryKeySelective(userInfoDto);
if(count <= 0) {
return ControllerUtil.returnDto(false, "失败", count);
}else {
return ControllerUtil.returnDto(true, "成功", count);
}
} catch (Exception e) {
logger.error("userInfo--updateByPrimaryKeySelective:系统异常");
return ControllerUtil.returnDto(false, "系统异常", count);
}
}
@ResponseBody
@RequestMapping(value = "modifyPwdById", method = RequestMethod.GET)
@ApiOperation(value = "修改密码", notes = "修改密码")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "人员信息id", required = true, paramType = "query"),
@ApiImplicitParam(name = "security_code",value = "验证码", required = true, paramType = "query"),
@ApiImplicitParam(name = "password",value = "新密码", required = true, paramType = "query")
})
public ResponseDto updateByPrimaryKeySelective(Integer id, String security_code, String password) {
int count = 0;
try {
//先对验证码是否正确做验证(此处暂未处理)
UserInfoDto userInfoDto = new UserInfoDto();
userInfoDto.setId(id);
userInfoDto.setPassword(password);
count = service.modifyPwdById(userInfoDto);
if(count <= 0) {
return ControllerUtil.returnDto(false, "失败", count);
}else {
return ControllerUtil.returnDto(true, "成功", count);
}
} catch (Exception e) {
logger.error("userInfo--modifyPwdById:系统异常");
return ControllerUtil.returnDto(false, "系统异常", count);
}
}
@ResponseBody
@RequestMapping(value = "deleteByPrimaryKey", method = RequestMethod.GET)
@ApiOperation(value = "根据id删除人员信息", notes = "根据id删除人员信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "人员信息id", required = true, paramType = "query")
})
public ResponseDto deleteByPrimaryKey(Integer id) {
int count = 0;
try {
count = service.deleteByPrimaryKey(id);
if(count <= 0) {
return ControllerUtil.returnDto(false, "失败", count);
}else {
return ControllerUtil.returnDto(true, "成功", count);
}
} catch (Exception e) {
logger.error("userInfo--deleteByPrimaryKey:系统异常");
return ControllerUtil.returnDto(false, "系统异常", count);
}
}
@ResponseBody
@RequestMapping(value = "selectById", method = RequestMethod.GET)
@ApiOperation(value = "根据id查询人员的所有信息", notes = "根据id查询人员的所有信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "人员信息id", required = true, paramType = "query")
})
public ResponseDto selectById(Integer id) {
UserInfoDto dto = service.selectById(id);
return ControllerUtil.returnDto(true, "成功", dto);
}
}
这个转载自:[springmvc集成swagger](https://segmentfault.com/a/1190000010554445)
如果是springboot项目记得在启动类开启swagger支持,配置扫描:
@EnableSwagger2
@ComponentScan()
访问:
http://localhost:端口号/项目名/swagger-ui.html