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 注解说明： Annotations · swagger-api/swagger-core Wiki · GitHub

Swagger RESTful API Documentation Specification：

OpenAPI-Specification/1.2.md at main · OAI/OpenAPI-Specification · GitHub

Swagger 注解使用 微服务之Swagger - 沧海一滴 - 博客园 有什么问题请指正。。。。。