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 有什麼問題請指正。。。。。