博客

Swagger与RestFul 集成 以及 注解使用Demo

  • Post author:
  • Post category:其他


准备工作：

1 按文档搭建Spring Boot 和 Swagger：

http://www.cnblogs.com/xiaohanghang/p/6018654.html
另附标准RestFul API规范:

RestFul API规范

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 RESTful API Documentation Specification：

       
      




       

        Swagger

       

       

        注解使用

       

       

        微服务之Swagger – 沧海一滴 – 博客园

       

       

        有什么问题请指正。。。。。

       
      










 






版权声明：本文为jun55xiu原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。