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 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：用对象接收参数时，描述对象的一个字段
其它若干@ApiResponse：HTTP响应其中1个描述
@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注解说明：https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodelSwagger RESTful API Documentation Specification：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#524-parameter-objectSwagger注解使用 http://www.cnblogs.com/softidea/p/6251249.html 有什么问题请指正。。。。。