Swagger与RestFul 集成 以及 注解使用Demo
准备工作：
1 按文档搭建Spring Boot 和 Swagger：
http://www.cnblogs.com/xiaohanghang/p/6018654.html
另附标准RestFul API规范: RestFul API规范
2 访问地址：
http://localhost:8080/swagger-ui.html
3 Swagger与标准RestFul（POST、PUT、DELETE、GET）集成Demo【以App应用模块为例】
/**
*
App操作类，
标准的RestFul接口
*/
@Api
(value =
"App操作类"
, description =
"App相关操作接口定义类"
)
@RestController
@RequestMapping
(value =
"/apps"
)
public class
BdAppController {
@Autowired
BdAppService
bdAppService
;//
Autowired
Service
//1 POST --- URL:
/apps
@ApiOperation
(value =
"创建"
, notes =
""
)
@ApiImplicitParam
(name =
"
app
"
, value =
"创建"
, required =
true
, dataType =
"
App
"
)
@RequestMapping
(method = RequestMethod.
POST
)
public
App release(
@RequestBody
App 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}
//4 PUT --URL/{appId} and RequestBody
//Post Many app objects
@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
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.* * 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.* * 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. * * This annotation must be used as a value of { @link ApiImplicitParams } * in order to be parsed. * * @see ApiImplicitParams */
5 Swagger 使用参考网址
Swagger
注解说明：
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel
Swagger RESTful API Documentation Specification：
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#524-parameter-object
Swagger
注解使用
http://www.cnblogs.com/softidea/p/6251249.html
有什么问题请指正。。。。。