准备工作:
1 按文档搭建Spring Boot 和 Swagger:
http://www.cnblogs.com/xiaohanghang/p/6018654.html
另附标准RestFul API规范:
RestFul API规范
3 Swagger与标准RestFul(POST、PUT、DELETE、GET)集成Demo【以App应用模块为例】
/**
*App操作类,标准的RestFul接口
*/
@Api(value = "App操作类", description ="App相关操作接口定义类")
@RestController
@RequestMapping(value = "/apps")
public classBdAppController {
@Autowired
BdAppServicebdAppService;//AutowiredService
//1 POST --- URL:/apps
@ApiOperation(value = "创建", notes ="")
@ApiImplicitParam(name = "app", value = "创建", required =true, dataType ="App")
@RequestMapping(method = RequestMethod.POST)
publicApp release(@RequestBodyApp app){
//todo
reutrn app;
}
}
或:
@ApiOperation(value = "创建", notes = "")
@RequestMapping(value = "/release",method = RequestMethod.POST)
public ResponseData newApp(
@ApiParam(name="app",value="产品临时对象",required = true)
@RequestBodyApp app){
//todo
reutrn app;
}
//2 GET (多条件查询分页)--- URL:/apps
@ApiOperation(value = "应用查询", notes = "")
@ApiImplicitParams(value = {
@ApiImplicitParam(paramType = "query", name = "appType", dataType = "String", required = true, value = "应用类型", defaultValue = "10"),
@ApiImplicitParam(paramType = "query", name = "appClassId", dataType = "String", required = true, value = "应用分类id"),
@ApiImplicitParam(paramType = "query", name = "appId", dataType = "String", required = true, value = "appId"),
@ApiImplicitParam(paramType = "query", name = "appName", dataType = "String", value = "应用名称"),
@ApiImplicitParam(paramType = "query", name = "appStatus", dataType = "String", required = true, value = "状态 0:已下架 1:正常"),
@ApiImplicitParam(paramType = "query",name = "page", value = "当前页码", required = true, dataType = "integer"),
@ApiImplicitParam(paramType = "query",name = "rows", value = "每页条数", required = true, dataType = "integer")
})
@RequestMapping(method = RequestMethod.GET)
public App list(@RequestParam("appType") String appType,
@RequestParam("appClassId") String appClassId,
@RequestParam("appId") String appId,@RequestParam("appName") String appName,
@RequestParam("appStatus") String appStatus,
@RequestParam(name = "page", defaultValue = "1") int page,
@RequestParam(name = "rows", defaultValue = "10") int rows) {
//todo
return 按规范自己封装;
}
//3 get ---url/{appid}
@ApiOperation(value = "获取产品详情", notes = "产品详情")
@ApiImplicitParam(paramType = "path", name = "appId", value = "产品appId",
required = true, dataType = "String")
@RequestMapping(value = "/{appId}", method = RequestMethod.GET)
private App getAppDetail(@PathVariable("appId") String appId) {
//todo
return 按规范自己封装;
}
//4 PUT --URL/{appId} and RequestBody
@ApiOperation(value="update", notes="")
@ApiImplicitParams(
value={
@ApiImplicitParam(paramType="path",name="appId",value="",
required=true,dataType = "String"),
@ApiImplicitParam(name="app",value ="App",
required=true,dataType ="App")
})
@RequestMapping(value="/{appId}",method =RequestMethod.PUT,
consumes = MediaTypes.JSON_UTF_8)
public App Appupdate(@PathVariable(value = "appId") String appId,
@RequestBody App app) {
//todo
return 按规范自己封装;
}
//Post Many app objects
@ApiOperation(value="创建多条APPs", notes="")
@RequestMapping(value="/postApps", method=RequestMethod.POST)
public String postApps(@ApiParam(name="apps",value="用户s",required = true)
@RequestBody List<App> apps) {
System.out.print(apps);
return "success";
}
4
常见swagger注解一览与使用
最常用的5个注解
@Api
:修饰整个类,描述Controller的作用
@ApiOperation :描述一个类的一个方法,或者说一个接口
@ApiParam :单个参数描述
@ApiModel :用对象来接收参数
@ApiProperty :用对象接收参数时,描述对象的一个字段
@ApiOperation :描述一个类的一个方法,或者说一个接口
@ApiParam :单个参数描述
@ApiModel :用对象来接收参数
@ApiProperty :用对象接收参数时,描述对象的一个字段
其它若干
@ApiResponse
:HTTP响应其中
1
个描述
@ApiResponses :HTTP响应整体描述
@ApiIgnore :使用该注解忽略这个API
@ApiClass
@ApiError @ApiErrors
@ApiParamImplicit @ApiParamsImplicit
@ApiResponses :HTTP响应整体描述
@ApiIgnore :使用该注解忽略这个API
@ApiClass
@ApiError @ApiErrors
@ApiParamImplicit @ApiParamsImplicit
/**
@ApiParam:
* Adds additional meta-data for operation parameters.
* <p/>
* This annotation can be used only in combination of JAX-RS 1.x/2.x annotations.
*/
/**
@ApiParamImplicit:
* Represents a single parameter in an API Operation. <p/>
* While {@link ApiParam} is bound to a JAX-RS parameter,
* method or field, this allows you to manually define a parameter in a fine-tuned manner.
* This is the only way to define parameters when using Servlets or other non-JAX-RS
* environments.
* <p/>
* This annotation must be used as a value of {@link ApiImplicitParams}
* in order to be parsed.
* * @see ApiImplicitParams
*/
5 Swagger 使用参考网址
Swagger
注解说明:
Annotations · swagger-api/swagger-core Wiki · GitHub
Swagger RESTful API Documentation Specification:
Swagger
注解使用
微服务之Swagger - 沧海一滴 - 博客园
有什么问题请指正。。。。。