restful风格的API

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

根路径

osvue.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://osvue.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: osvue.com api
  description: 描述接口信息
  contact:
    name: yiming
    url: http://osvue.com
    email: 888@qqq.com
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
schemes: 
  - http
  
host: osvue.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

分组

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

swagger.docket.restcontroller.title=group-restcontroller
swagger.docket.restcontroller.base-package=com.osvue.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={"用户操作接口"})