JEESZ REST服务接口文档

1、            引言

1.1、       REST介绍

REpresentational State Transfer (REST) 是一种架构原则,其中将 web 服务视为资源,可以由其 URL 唯一标识。RESTful Web 服务的关键特点是明确使用 HTTP 方法来表示不同的操作的调用。

REST 的基本设计原则对典型 CRUD 操作使用 HTTP 协议方法:

POST - 创建资源

GET - 检索资源

PUT – 更新资源

DELETE - 删除资源

REST 服务的主要优势在于:

它们是跨平台 (Java、.net、PHP 等)高度可重用的,因为它们都依赖基本 HTTP 协议。

它们使用基本的 XML,而不是复杂的 SOAP XML,使用非常方便。

基于 REST 的 web 服务日益成为后端企业服务集成的首选方法。与基于 SOAP 的 web 服务相比,它的编程模型简单,而本机 XML(而不是 SOAP )的使用减少了序列化和反序列化过程的复杂性,并且不再需要其他作用相同的第三方库。

1.2、       编写目的

编写本文的目的是为了将系统功能进行模块化、服务化,将用户的操作以服务的方式提供。系统与系统之间遵循服务规范,将系统与系统之间的交互转为定制化服务交互,以实现系统与系统之间的集成。

1.3、       编写原则

可寻址性(AddressabilityREST 中的所有东西都基于资源 的概念。资源与 OOP 中的对象或其他名词不同,它是一种抽象,必须可以通过 URI 寻址或访问。

接口一致性(Interface uniformity与 SOAP 或其他标准不同,REST 要求用来操纵资源的方法或动词不是任意的。这意味着 RESTful 服务的开发人员只能使用 HTTP 支持的方法,比如 GET、PUT、POST、DELETE 等等。因此不需要使用 WSDL 等服务描述语言。

无状态(Statelessness为了增强可伸缩性,服务器端不存储客户机的状态信息。这使服务器不与特定的客户机相绑定,负载平衡变得简单多了。这还让服务器更容易监视、更可靠。

具象(Representational客户机总是与资源的某种具象交互,绝不会直接与资源本身交互。同一资源还可以有多个具象。理论上说,持有资源的具象的任何客户机应该有操纵底层资源的足够信息。

连通性(Connectedness任何基于 REST 的系统都应该预见到客户机需要访问相关的资源,应该在返回的资源具象中包含这些资源。例如,可以以超链接的形式包含特定 RESTful 服务的操作序列中的相关步骤,让客户机可以根据需要访问它们。基于 REST 的 Web 服务日益成为后端企业服务集成的

1.4、       变更历史


序号


变更人员


变更时间


变更内容


1


Jeesz


2014-10-02


我的收藏服务3.1、3.2、4.3、5.4(仅仅以我的收藏部分服务为实例),用户根据自己的业务编写相关的服务文档即可

 

2、      服务使用说明

2.1、     当前系统已经提供的服务

2.2、     GET方式调用服务

说明:

1.       请求方式包括:GET (这里以area服务为实例,GET对应每一个服务Resource中的@RequestMapping(value = "treeData", method = RequestMethod.GET))

2.       请求URL:rest服务请求地址,对应XXXServiceResource.java的mapping配置中的value

@RequestMapping(value = "treeData", method = RequestMethod.GET))

3.       其中GET请求只包含了请求方式和请求的URL,返回的结果以json格式返回给客户端

2.3、     POST、DELETE、UPDATE方式调用服务

说明:

1.       请求方式选择POST、DELETE、UPDATE(这里以保存收藏功能为例(PUT请求),对应每一个服Resource中的@RequestMapping(value = "save", method = RequestMethod.PUT))

2.       Json参数: 其中POST、DELETE、UPDATE可能传递参数通过json,也可能通过路径直接拼接参数,这边以传递json到服务端为实例,对应服务端代码:

public JSONObject save(@RequestBody JSONObject obj, BookmarkTag bookmarkTag) {

3.       请求URL:rest服务请求地址,对应XXXServiceResource.java的mapping配置中的value

@RequestMapping(value = " save", method = RequestMethod.PUT))

4.       返回的结果以json格式返回给客户端

3、      服务列表(这边以我的收藏服务为例)

3.1、     添加标签分类


请求方式


PUT


服务URL


http://localhost:8080/jeesz-service-web/rest/bookmark/save


路径参数?*描述



参数类型(Type)


application/json


参数描述


{“name”:”jeesz”}

备注:

name:标签名称


返回值类型(Type)


application/json


描述


添加成功:

{result:”添加成功”,

”name”:”jeesz”,” bookmarkTagId”:”123456789”}

提示:返回结果由用户根据自己的业务去扩充

3.2、     删除分类标签


请求方式


DELETE


服务URL


/bookmark/delete? bookmarkTagId =xxxx


路径参数?*描述


bookmarkTagId:分类标签id


参数类型(Type)


String


返回值类型(Type)


application/json


描述


添加成功:{“result”:”删除成功”}

提示:返回结果由用户根据自己的业务去扩充

3.3、     更新分类标签


请求方式


POST


服务URL


/bookmark/update


路径参数?*描述



参数类型(Type)


application/json


参数描述


{“id”:”标签id”,“name”:”标签name”}

备注:

id:标签id

name:标签名称


返回值类型(Type)


application/json


描述


添加成功:{“result”:”更新成功”}

提示:返回结果由用户根据自己的业务去扩充

3.4、     获取分类标签列表


请求方式


GET


服务URL


/bookmark/list?pageNo=1&pageSize=3


路径参数?*描述


pageNo:当前页

pageSize:每页显示多少条


参数类型(Type)



参数描述


通过request获取参数(根据自己的业务,可以通过其他方式获取,如路径参数?*、路径拼接参数等)


返回值类型(Type)


application/json


描述


{"pageNo":1,"pageSize":1,"count":42,

"list":[{"id":"de0163b614b34c0ba99590e8e63b9e3e",

"isNewRecord":false,"createDate":"2016-02-28 21:40:36","updateDate":"2016-02-28 21:40:36","bookmarktagname":"jeesz"}]

知识分享可参考源码:http://minglisoft.cn/technology

朋友需要请加球球:二零四二八四九二三七

时间: 2024-11-05 06:25:37

JEESZ REST服务接口文档的相关文章

JEESZ REST 服务接口文档

1. 引言..................................................................................................................................... 1.1. REST 介绍...................................................................................................

3-JEESZ分布式框架--REST服务接口文档

1. REST介绍 REpresentational State Transfer (REST) 是一种架构原则,其中将 web 服务视为资源,可以由其 URL 唯一标识. RESTful Web 服务的关键特点是明确使用 HTTP 方法来表示不同的操作的调用. REST 的基本设计原则对典型 CRUD 操作使用 HTTP 协议方法: POST - 创建资源 GET - 检索资源 PUT – 更新资源 DELETE - 删除资源 REST 服务的主要优势在于: 它们是跨平台 (Java..net

用Swagger生成接口文档

Swagger简介 在系统设计的时候,各个应用之间往往是通过接口进行交互的.因此接口的定义在整个团队中就变得尤为重要.我们可以把接口的规范用接口描述语言进行描述,然后Swagger可以根据我们定义的接口规范生成对应的接口文档.它生成的接口文档提供了接口测试功能.我们只需要填上对应的参数,然后点击调用,就可以完成一次接口测试,非常方便.就像下图展示的那样. 不仅如此,Swagger还能够根据接口规范自动生成对应的接口代码!比如Java客户端代码.Java服务端代码等.这个东西减少了接口规范的沟通成

springmvc集成swagger实现接口文档自动化生成

一直苦于文档整理工作,因为这是一个很无聊的工作,偶然在网上看到了swagger这东西,感觉不错,于是动手集成了一下,眼前一亮 Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 费话少说,下面来看一下集成的过程,我用的环境是:jdk1.8+tomc

[API]使用Blueprint来高雅的编写接口文档

Blueprint(http://apiary.io/)是apiary公司的工具包,用来编写API文档,类似于Markdown,是一种标记语言. 对于习惯使用RESTful API的同志们来说,使用Blueprint可以快速的写出高雅大气的文档: 下面以一个Github中的Gist服务为例,简单的演示一下Blueprint的应用. 原文地址:http://blog.callmewhy.com/2014/06/05/blueprint-tutorial/ API Blueprint是一套API描述

Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 mvc接口文档

两种方案 一.Swagger 配置 web Api 接口文档美化 二.通过NodeJS 发布Swagger UI 配置api 文档 先说一下简单的 Swagger 配置 web Api  Swagger-UI本身只提供在线测试功能,要集成它还需要告诉它本项目提供的各种服务和参数信息.这里就需要一些工作量了,不过好在许多第三方库已经给我们完成了这一工作.我这里用的是Swashbuckle,使用它也比较简单,直接使用Nuget添加其程序包即可: 1.初始化包  PM> Install-Package

解决访问swaggerUI接口文档显示basic-error-controler问题

问题描述 使用swagger生成接口文档后,访问http://localhost:8888/swagger-ui.html#/,显示如下: 有些强迫症的我,感觉看起来很不舒服,结果百度了好久,找到解决方案,刚接触spring boot对于很多api还不是很熟悉,先mark再说 代码如下: package com.course.config; import com.google.common.base.Predicates; import org.springframework.context.a

spring接口文档注解:@ApiOperation(转)

spring接口文档注解:@ApiOperation @ApiOperation不是spring自带的注解是swagger里的 com.wordnik.swagger.annotations.ApiOperation; @ApiOperation和@ApiParam为添加的API相关注解,个参数说明如下: @ApiOperation(value = "接口说明", httpMethod = "接口请求方式", response = "接口返回参数类型&qu

get_k_data 接口文档 全新的免费行情数据接口

get_k_data 接口文档 全新的免费行情数据接口 原创: Jimmy 挖地兔 2016-11-06 前言在tushareAPI里,曾经被用户喜欢和作为典范使用的API get_hist_data,经历了数据的一些些缺失和一丢丢错误之后,在用户们的齐声呼“换”之下,终于要变成tushare中的一个history.迎来的是一个集分钟数据.日周月数据,前后复权数据,揽括所有股票.指数和ETF的get_k_data.未来,还将加入期货期权等品种,所以,get_k_data或许将会成为未来一个“著名