目录
一、Swagger介绍
swagger用于定义API文档，返回数据格式是json，用的是restful风格。
优点：
- 前后端分离开发
- API文档非常明确
- 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
- 传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
- spring boot与swagger的集成简单
spring boot中使用swagger2构建RESTful APIs
二、技术与IDE
spring boot
IntelliJ IDEA
maven
swagger
三、具体应用
ContentColumnController.java
package com.enterprisename.xserver.saas.basic.api.content;
import com.enterprisename.xserver.baas.utilities.error.ErrCodeConstant;
import com.enterprisename.xserver.baas.utilities.error.ErrMsgConstant;
import com.enterprisename.xserver.baas.utilities.exception.CustomException;
import com.enterprisename.xserver.baas.utilities.tools.validator.ValidatorUtils;
import com.enterprisename.xserver.baas.utilities.tools.validator.groups.AddGroup;
import com.enterprisename.xserver.baas.utilities.tools.validator.groups.UpdateGroup;
import com.enterprisename.xserver.saas.basic.entity.content.ContentColumn;
import com.enterprisename.xserver.saas.basic.service.content.ContentColumnService;
import com.enterprisename.xserver.saas.common.account.entity.response.ResponseData;
import com.enterprisename.xserver.saas.common.shiro.jwt.JwtTokenUtil;
import io.swagger.annotations.*;
import org.apache.commons.beanutils.ConvertUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;
@Api(tags = "ContentColumn",description = "内容栏目接口")
@RestController
@RequestMapping(value = "/contentColumn")
@ApiResponses({
@ApiResponse(code = ErrCodeConstant.ERR_INVALID_INPUT_PARAM, message = ErrMsgConstant.MSG_INVALID_INPUT_PARAM),
@ApiResponse(code = ErrCodeConstant.ERR_NO_AUTHENTICATE, message = ErrMsgConstant.MSG_NO_AUTHENTICATE),
@ApiResponse(code = ErrCodeConstant.ERR_NO_AUTHORIZE, message = ErrMsgConstant.MSG_NO_AUTHORIZE),
@ApiResponse(code = ErrCodeConstant.ERR_INVALID_TOKEN, message = ErrMsgConstant.MSG_INVALID_TOKEN)
})
public class ContentColumnController {
@Autowired
private ContentColumnService contentColumnService;
@Autowired
private JwtTokenUtil jwtTokenUtil;
/**
* 创建内容栏目
* @param contentColumn
* @return
*/
@ApiOperation(value = "创建内容栏目", httpMethod = "POST", notes = "创建结果")
@RequestMapping(value = "/create",method = RequestMethod.POST)
@ApiImplicitParams({
@ApiImplicitParam(name = "groupId",value = "所属group",required = true,dataType = "Long", paramType = "query"),
@ApiImplicitParam(name = "parent",value = "父级栏目",required = true,dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "colName",value = "栏目名称",required = true,dataType = "String", paramType = "query")
})
@ApiResponses({
@ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_ADD_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_ADD_FAILED),
@ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_ALREADY_EXIST, message = ErrMsgConstant.MSG_CONTENTCOLUMN_ALREADY_EXIST),
})
public ResponseData create(@RequestBody ContentColumn contentColumn, HttpServletRequest request){
ValidatorUtils.validateEntity(contentColumn,AddGroup.class);
Long uid=getUuid(request);
return contentColumnService.createContentColumn(contentColumn,uid);
}
/**
* 更新内容栏目
* @param contentColumn
* @return
*/
@ApiOperation(value = "更新内容栏目", httpMethod = "POST", notes = "更新结果")
@RequestMapping(value = "/update/{uuid}",method = RequestMethod.POST)
@ApiImplicitParams({
@ApiImplicitParam(name = "uuid", value = "内容栏目id", required = true, dataType = "Long", paramType = "query")
})
@ApiResponses({
@ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_UPDATE_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_UPDATE_FAILED),
@ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_INVALID, message = ErrMsgConstant.MSG_CONTENTCOLUMN_INVALID),
})
public ResponseData update(@RequestBody ContentColumn contentColumn,HttpServletRequest request,@PathVariable("uuid") String uuid){
contentColumn.setUuid(Long.parseLong(uuid));
ValidatorUtils.validateEntity(contentColumn, UpdateGroup.class);
Long uid = getUuid(request);
return contentColumnService.updateContentColumnInfo(contentColumn,uid);
}
/**
* 删除内容栏目
*/
@ApiOperation(value = "删除内容栏目", httpMethod = "POST", notes = "删除结果")
@RequestMapping(value = "/delete", method = RequestMethod.POST)
@ApiImplicitParams({
@ApiImplicitParam(name="contentColumnIds",value="内容栏目id集合",required = true,dataType = "Long[]",paramType = "query")
})
@ApiResponses({
@ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_DELETE_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_DELETE_FAILED),
@ApiResponse(code = ErrCodeConstant.ERR_INVALID_INPUT_PARAM, message = ErrMsgConstant.MSG_INVALID_INPUT_PARAM),
})
public ResponseData delete(@RequestBody HashMap map) {
String contentColumnIdsStr= (String) map.get("contentColumnIds");
String[] contentColumnIdsTemp=contentColumnIdsStr.split(",");
Long[] columnIds = (Long[]) ConvertUtils.convert(contentColumnIdsTemp,Long.class);
return contentColumnService.deleteBatch(columnIds);
}
/**
* 查询内容栏目列表
* @return
*/
@ApiOperation(value="查询内容栏目列表",httpMethod = "POST",notes = "返回内容栏目列表")
@RequestMapping(value="/list",method = RequestMethod.POST)
@ApiResponses({
@ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_SEARCH_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_SEARCH_FAILED),
})
public ResponseData contentColumnList(){
return contentColumnService.queryAllContentColumn();
}
/**
* 查询指定内容栏目信息
* @param
* @return
*/
@ApiOperation(value = "查询指定内容栏目信息", httpMethod = "POST", notes = "返回内容栏目信息")
@RequestMapping(value = "/info", method = RequestMethod.POST)
@ApiImplicitParams({
@ApiImplicitParam(name="uuid",value="内容栏目id",required=true,dataType = "Long",paramType = "path")
})
@ApiResponses({
@ApiResponse(code = ErrCodeConstant.ERR_CONTENTCOLUMN_SEARCH_FAILED, message = ErrMsgConstant.MSG_CONTENTCOLUMN_SEARCH_FAILED),
})
public ResponseData contentColumnInfoByColumnId(@RequestBody Map<String,Object> reqMap, HttpServletRequest request){
Long contentColumnId=(Long) reqMap.get("uuid");
return contentColumnService.queryContentColumnInfoByContentColumnId(contentColumnId);
}
private Long getUuid(HttpServletRequest request) {
String token = request.getHeader("Authorization");
String uuid = jwtTokenUtil.getUidFromToken(token);
if (uuid == null)
throw new CustomException(ErrCodeConstant.ERR_INVALID_TOKEN,ErrMsgConstant.MSG_INVALID_TOKEN);
return Long.parseLong(jwtTokenUtil.getUidFromToken(token));
}
}
四、启动应用程序访问url
http://localhost:8080/swagger-ui.html
五、返回结果
六、API注解详情
| 作用范围 | API | 使用位置 |
| 对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
| 协议集描述 | @Api | 用于Controller类上 |
| 协议描述 | @ApiOperation | 用在Controller的方法上 |
| Response集 | @ApiResponses | 用在Controller的方法上 |
| Response | @ApiResponse | 用在@ApiResponses里面 |
| 非对象参数集 | @ApiImplicitParams | 用在Controller的方法上 |
| 非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里面 |
| 描述返回对象的意义 | @ApiModel | 用在返回对象的类上 |
@RequestMappping此注解的推荐配置
value，method，produces
@ApiImplicitParam
| 属性 | 取值 | 作用 |
| paramType | 查询参数类型 | |
| path | 以地址的形式提交数据 | |
| query | 直接跟参数完成自动映射赋值 | |
| body | 以流的形式提交 仅支持POST | |
| header | 参数在request headers里边提交 | |
| form | 以form表单的形式提交 仅支持POST | |
| dataType | 参数的数据类型 只作为标志说明 并没有实际验证 | |
| Long | ||
| String | ||
| name | 接收参数名 | |
| value | 接收参数的意义描述 | |
| required | 参数是否必填 | |
| true | 必填 | |
| false | 非必填 | |
| defaultValue | 默认值 |
说明：
- @Api:用在类上，说明该类的作用
- @ApiOperation:用在方法上，说明方法的作用
- @ApiImplicitParams:用在方法上包含一组参数说明
- @ApiImplicitParam:用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
-
paramType:参数放到哪个地方
header-->请求参数的获取：@RequestHeader
query-->请求参数的获取：@RequestParam
path（用于restful接口）-->请求参数的获取：@PathVariable
body（不常用）
form（不常用）
-
name:参数名
-
dataType:参数类型
-
required:参数是否必须传入
-
value:参数的意思
-
defaultValue:参数的默认值
- @ApiResponses:用于表示一组响应
- @ApiResponse:用在@ApiResponses中，一般用于表达一个错误的响应信息
- code:数字，例如400
- message：信息，例如“请求参数没填好!”
- response:抛出异常的类
- @ApiModel:描述一个model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
- @ApiModelProperty:描述一个model的属性
以上这些就是最常用的注解了
4万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
