REST-API开发指南

Controller示例

在服务工程的com.hxhealth.xxx.controller下创建一个XXController.java

  @Controller 
  public  class  XXController  {
  }

CookieValue示例

注释表明，CookieValue方法的参数可以绑定到HTTP的Cookie。支持在Servlet和Portlet环境注明处理方法。

  @RequestMapping  ("/userList") 
  public  String  delete(@CookieValue("JSESSIONID")  String sessionId ){ 
  }

RequestHeader示例

  @RequestMapping("/showJavaBlogerInfo") 
  public  void showHeadInfo( 
  @RequestHeader("User-Agent"),String userAgent, 
  @RequestHeader("Accept-Encoding"),String encoding, 
  @RequestHeader("Keep-Alive"),long keepAlive,  ){ 
  }

HttpMethod

  @RequestMapping  (metthod=RequestMethod.DELETE) 
  public  void  delete  (@RequestParam  String userId)  { 
  System.out.println(userId); 
  }

RequestMapping

可以在@RequestMapping注解中用{}来表明它的变量部分，例如：

  @RequestMapping("/users/{username}")

RequestParam

参数绑定说明：当方法中带有参数时，可以采用@RequestParam 绑定单个请求参数值

  @RequestMapping(value =  {"/selectPaperDatum}"}, method =  RequestMethod.GET)
  public  ItooResult selectPaperDatum(@RequestParm("studentId")  String studentId)  {
  }

---

API文档开发指南

说明

开发平台API文档是通过在Rest接口编写swagger注解，通过技术组件反射来动态生产API文档元数据信息。下面具体说明一下注解的使用。

• @Api 描述类/接口的主要用途
• @ApiOperation 描述方法用途
• @ApiImplicitParam 描述方法的参数
• @ApiImplicitParams 描述方法的参数(Multi-Params)
• @ApiIgnore 忽略某类/方法/参数的文档

@Api

用于类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源

  @Api(value =  "xxx", description =  "xxx")

注解	属性	备注
Api	value	url的路径值
	tags	如果设置这个值、value的值会被覆盖
	description	对api资源的描述
	basePath	基本路径可以不配置
	position	如果配置多个Api 想改变显示的顺序位置
	produces	For example, “application/json, application/xml”
	consumes	For example, “application/json, application/xml”
	protocols	Possible values: http, https, ws, wss.
	authorizations	高级特性认证时配置
	hidden	配置为true 将在文档中隐藏

@ApiOperation

用于方法上，说明方法的作用，每一个url资源的定义

  @ApiOperation(value =  "xxx",httpMethod="POST", notes=  "xxx",response=String.class)

注解	属性	备注
ApiOperation	value	url的路径值
	tags	如果设置这个值、value的值会被覆盖
	notes	对资源的描述
	position	如果配置多个 想改变显示的顺序位置
	produces	For example, “application/json, application/xml”
	consumes	For example, “application/json, application/xml”
	protocols	Possible values: http, https, ws, wss.
	authorizations	高级特性认证时配置
	hidden	配置为true 将在文档中隐藏
	response	返回的对象
	responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
	httpMethod	GET, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
	code	http的状态码 默认 200
	extensions	扩展属性

@ApiParam

用于方法、参数、字段上，请求属性

  @ApiParam(value =  "Created user object", required =  true)
  public  ResponseEntity<User> createUser(@RequestBody  User user)

注解	属性	备注
ApiParam	name	属性名称
	value	属性值
	defaultValue	默认属性值
	allowableValues	可以不配置
	required	是否属性必填
	access
	allowMultiple	默认为false
	hidden	隐藏该属性
	example	示例

@ApiResponses

用于方法上，响应集配置

  @ApiResponses({  @ApiResponse(code =  400, message =  "Invalid Order")  })

@ApiResponse

用于方法上，响应配置

  @ApiResponse(code =  400, message =  "Invalid user supplied")

注解	属性	备注
ApiResponse	code	http的状态码
	message	描述
	response	默认响应类 Void
	reference	参考ApiOperation中配置
	responseHeaders	参考 ResponseHeader 属性配置说明
	responseContainer	参考ApiOperation中配置

@ResponseHeader

用于方法上，响应头设置

  @ResponseHeader(name="head1",description="response head conf")

注解	属性	备注
	name	响应头名称
	description	头描述
	response	默认响应类 Void
	responseContainer	参考ApiOperation中配置

@ApiImplicitParams

用于方法上，包含一组参数说明

@ApiImplicitParam

用于方法上，用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

注解	属性	备注
	paramType	参数放在哪个地方
	name	参数代表的含义
	value	参数名称
	dataType	参数类型，有String/int，无用
	required	是否必要
	defaultValue	参数的默认值

@ApiModel

用于类上，描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候

@ApiModelProperty

用于方法、字段上，描述一个model的属性

@ApiIgnore

用于类，属性，方法上，忽略某项api,使用@ApiIgnore