文档章节

Dubbo 03 Restful风格的API

o
 osc_ogi0qclx
发布于 2019/08/25 05:59
字数 1092
阅读 15
收藏 0

精选30+云产品,助力企业轻松上云!>>>

[TOC]

Dubbo03

restful风格的API

Representational State Transfer,资源表现层状态转换

根路径

mashibing.com

协议

http://

版本

v1

可以直接写在URL上,或者写在header中传递“Accept-Version: v2”

 @RequestMapping(headers = "Accept-Version=v2",value = "models",method = RequestMethod.GET)

用HTTP协议里的动词来实现资源的增删改查

GET 用来获取资源,
POST 用来新建资源(也可以用于更新资源)。
DELETE 用来删除资源。 
UPDATE http://api.chesxs.com/v1/fence 更新围栏信息 

用例

单个资源

http://mashibing.com/api/v1/Users/1 使用Get方法获取id是1的用户数据

         正确:GET /model/models/{id}        #获取单个资源

         正确:POST /model/models            #创建单个资源

         正确:PUT /model/models/{id}        #更新单个资源

         正确:DELETE /model/models/{id}   #删除单个资源

         正确:PATCH /model/models/{id}   #更新单个资源(只传差异)

         正确:GET /model/configRuleFile    #获取单个资源(如果仅有一个值时,应采用单数方式)

返回结果:

如果指定的资源并不存在,那么应该返回404 Not Found状态,否则应该返回200 OK状态码

资源集合

对于资源集合,支持以下URL

   正确: GET /model/models                             #获取资源列表

   正确: GET /model/models?ids={ids}             #批量获取资源列表

   正确: DELETE /model/models?ids={ids}       #批量删除资源列表

   返回结果:

如果列表为空,则应该空数组

响应结果

响应状态码 含义
成功 200 调用成功
201 创建成功
204 执行成功,但无返回值
失败 400 无效请求
401 没有登录
403 没有权限
404 请求的资源不存在
500 服务内部错误

swagger(丝袜哥)

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统,数以千计的开发人员,使用几乎所有的现代编程语言,都在支持和使用Swagger。使用Swagger生成API,我们可以得到交互式文档,自动生成代码的SDK以及API的发现特性等。

OpenAPI

OpenAPI规范是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息

比如:

  • 有关该API的一般性描述
  • 可用路径(/资源)
  • 在每个路径上的可用操作(获取/提交...)
  • 每个操作的输入/输出格式

根据OpenAPI规范编写的二进制文本文件,能够像代码一样用任何VCS工具管理起来一旦编写完成,API文档可以作为:

  • 需求和系统特性描述的根据
  • 前后台查询、讨论、自测的基础
  • 部分或者全部代码自动生成的根据
  • 其他重要的作用,比如开放平台开发者的手册...

资源

官网

https://swagger.io/

在线编辑器

http://editor.swagger.io/

编写API文档

我们可以选择使用JSON或者YAML的语言格式来编写API文档

swagger: '2.0'
info:
  version: 1.0.0
  title: mashibing.com api
  description: 马老师的官网接口
  contact:
    name: yiming
    url: http://mashibing.com
    email: 888@qqq.com
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
schemes: 
  - http
  
host: mashibing.com
basePath: /api/v1

paths:
  /user/{userid}:
    get:
      summary: 获取一个用户
      description: 根据id获取用户信息
      parameters: 
        - name: userid
          in: path
          required: true
          description: 用户id
          type: string
      responses:
        200:
          description: OK
    
  /user:
    get:
      summary: 返回List 包含所有用户
      description: 返回List 包含所有用户
      parameters:
          - name: pageSize
            in: query
            description: 每页显示多少
            type: integer
          - name: pageNum
            in: query
            description: 当前第几页
            type: integer
      
      responses:
        200:
          description: OK
          
          schema:
            type: array
            items: 
              required:
                - username
              properties:
                username:
                  type: string
                password:
                  type: string    
 

整合SpringBoot

官方依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
</dependency>
<dependency>
        <groupId>org.codehaus.jackson</groupId>
        <artifactId>jackson-core-asl</artifactId>
        <version>1.9.13</version>
</dependency>

第三方

https://github.com/SpringForAll/spring-boot-starter-swagger

依赖引入

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

启用注解

http://localhost:803//v2/api-docs

http://localhost:8080/swagger-ui.html

分组

1566031879599

swagger.docket.controller.title=group-controller
swagger.docket.controller.base-package=com.mashibing.springboot.controller

swagger.docket.restcontroller.title=group-restcontroller
swagger.docket.restcontroller.base-package=com.mashibing.springboot.controller.rest

实体模型

	@ApiModelProperty(value = "权限id", name = "id",dataType = "integer",required = true,example = "1")
    private Integer id;

接口方法

	@ApiOperation(value = "获取所有权限")
	@RequestMapping(value = "list",method = RequestMethod.GET)
	public List<Permission> list() {
		
		return permissionSrv.findAll();
	}


	@ApiOperation(value = "添加权限")
	@RequestMapping("update")
	public RespStat update(@ApiParam(name="permission",required = true, example = "{json}",value = "权限对象") @RequestBody Permission permission) {
		
		System.out.println("permission:" + ToStringBuilder.reflectionToString(permission));
		permissionSrv.update(permission);
		return RespStat.build(200);
	}

接口类描述

@Api(value = "用户权限管理",tags={"用户操作接口"})

o
粉丝 0
博文 500
码字总数 0
作品 0
私信 提问
加载中
请先登录后再评论。
OpenAPI接口的发布,文档,测试----Swagger+Dubbo Rest+Easyrest

背景 对外开放的接口,需要清晰的接口文档,方便客户端进行测试,目前restful风格的接口定义是最好理解,调用和测试的接口风格;服务提供端也需要一种简单的办法,把已有的服务接口发布为res...

PageYi
2018/10/23
1.8K
1
推荐几个自己写的Java后端相关的范例项目(转载)

http://wosyingjun.iteye.com/blog/2312553 这里推荐几个自己写的范例项目,主要采用SSM(Spring+SpringMVC+Mybatis)框架,分布式架构采用的是(dubbo+zookeeper)。范例项目的好处是简单易...

指尖的舞者
2016/09/27
505
0
关于 Java API for RESTful Web Services (JAX-RS) 介绍

关于 Java API for RESTful Web Services (JAX-RS) 介绍 一.webService介绍 之前的文章我介绍了cxf webService的使用,它是一种以wsdl发布的形式。下面结合我在了解说明下两组概念: jax-ws...

osc_mt5p9sib
2018/08/15
7
0
springboot,dubbo,nacos,spring-cloud-alibaba的整合

  最近,自去年阿里开源了dubbo2.7及一系列产品后,阿里也打造了融入spring-cloud 的生态体系,本人关注,今年阿里开源的的spring-cloud-alibaba基本孵化完成,笔者更是对这一系统的东西关...

osc_c10h48oh
2019/07/30
10
0
基于 Spring + Dubbo 开发分布式REST服务实战

本课程主要是使用 Spring技术栈 + dubbo 开发一个类似当当的图书电商后台的实战教程。 课程特点: 1.课程的技术体系足够系统、全面以及细致:课程中涉及的主要技术包括: Spring IO (依赖版本...

登录404
2017/05/17
1.4K
3

没有更多内容

加载失败,请刷新页面

加载更多

OSChina 周日乱弹 —— 那么长的绳子,你这是放风筝呢

Osc乱弹歌单(2020)请戳(这里) 【今日歌曲】 @ 巴拉迪维:黑豹乐队的单曲《无地自容》 耳畔突然响起旋律,是那首老歌。中国摇滚有了《一无所有》不再一无所有;中国摇滚有了《无地自容》不...

小小编辑
18分钟前
31
1
《吐血整理》-顶级程序员书单集

你知道的越多,你不知道的越多 给岁月以文明,而不是给文明以岁月 前言 王潇:格局决定了一个人的梦想,梦想反过来决定行为。 那格局是什么呢? 格局是你能够看见的深度、广度和密度。 王潇认...

敖丙
2019/12/11
0
0
我可以在Android版式中加下划线吗? - Can I underline text in an Android layout?

问题: 如何在Android布局xml文件中定义带下划线的文本? 解决方案: 参考一: https://stackoom.com/question/A31z/我可以在Android版式中加下划线吗 参考二: https://oldbug.net/q/A31z/...

法国红酒甜
21分钟前
18
0
干掉ELK | 使用Prometheus+Grafana搭建监控平台

什么是Prometheus? Prometheus是由SoundCloud开发的开源监控报警系统和时序列数据库(TSDB)。Prometheus使用Go语言开发,是Google BorgMon监控系统的开源版本。 Prometheus的特点 · 多维度...

木九天
40分钟前
34
0
拉勾网拉你上勾

预览 需求简介 拉勾网是一个互联网行业的一个招聘网站,上面有许多职位,于是乎,小编想提取指定职位的基本信息(职位名,薪水,工作经验,工作地点,教育背景),然后插入 MongoDB 数据库,...

木下瞳
2019/04/17
20
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部