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#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  有什么问题请指正。。。。。