Resuful和OpenApi_http的几种请求方式

ResufulResuful是一种开发思想，是一种网络应用程序的设计风格和开发方式，基于http,可以使用xml或者json格式定义。具体可以查看Resuful的百度百科。总结起来的话就是：每一个URI代表一种资源客户端和服务器之间，传递这种资源的某种表现层客户端通过http的几种请求方式，对服务器资源进行操作，实现“表现层状态转化”请求的URI是不应该包含动词的，动词完全由get、...

zhoudado921

3104人浏览 · 2020-04-27 10:23:27

zhoudado921 · 2020-04-27 10:23:27 发布

Resuful

Resuful是一种开发思想，是一种网络应用程序的设计风格和开发方式，基于http,可以使用xml或者json格式定义。具体可以查看Resuful的百度百科。
总结起来的话就是：

每一个URI代表一种资源
客户端和服务器之间，传递这种资源的某种表现层
客户端通过http的几种请求方式，对服务器资源进行操作，实现“表现层状态转化”
请求的URI是不应该包含动词的，动词完全由get、post、delete、put、patch等方法进行表现
下面进行讲解几种方法
get：获取数据，信息存储在url中，不安全，无法传递太大的数据
head：head就像get，只不过服务器接受到head请求后只返回响应头，而不会发送响应内容。当我们只需要查看某个页面的状态的时候，使用head是非常高效的，因为在传输的过程中省去了页面内容
post:一般用于表单的提交数据。数据包含在请求体中
put:从客户端向服务器传送的数据取代执行的文档的内容
patch：实体中包含一个表，表中说明与该URI所表示的原内容的区别。
delete:请求服务器删除指定的页面

put、post、patch的区别：
一般简单的会听到这样的话：post是新增，put是修改整个资源，patch是修改局部资源。那么最基础的区别是什么呢？
post和put的区别：
post请求的URI表示处理该封闭实体的资源，该资源可能是个数据接收过程。某种协议的网关或接收注解的独立实体。然而put中的URI表示请求中封闭的实体–用户代理知道URI的目标，并且服务器无法将请求应用到其他资源。如果服务器希望该请求应用到另一个URI，就必须发送一个301响应，用户代理可以通过自己的判断来决定是否转发该请求。
post不是幂等、put是幂等
put和patch都可以进行更新资源，但是如果页面只能进行更新一个字段，而不是整个整体，那么就需要用到patch，可以减少带宽的使用。put是用来更新整体的。

OpenApi

openApi就是开放api。也就是网站的一些服务商将自己的网站服务封装成一系列的api开放出去，供第三方开发者使用。

ApI文档应该是构建应用程序的基础，这个原则正是API-First开发的全部内容。现在流行的前后端分离的开发思想，那么在设计完接口之后，前后端都可以同时开发。

那么如何编写openApi呢？Resuful思想是基础，在此基础上展示出你的接口。简单的可以理解为一种格式：可用json和yaml两种形式展示。最终展示为网页的形式：
在这里插入图片描述
我这个是将代码上传至GitLab上之后，打开文档会直接被渲染成网页的形式。当然也有一些软件用于展示页面：如swagger工具。

openApi文档的三个必需的部分或对象：
1、openapi----openApi规范版本的语义版本号
2、info----有关api的元数据
3、paths–api的可用路径和操作
openapi对象声明了用于文档的规范的版本。该版本对于用户理解文档的结构至关重要，更重要的是，对于可能为了验证目的而获取文档或创建虚拟服务的任何工具，info对象提供有关API本身的基本信息。标题和版本是必填字段，我们可以选择包含其他信息，例如说明，联系和许可信息。
具体可以查看openApi的官方文档：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

以下是我写的例子：仅供参考

openapi_userApi.yaml

openapi: 3.0.0
info:
  title: "HttpServer的Api接口"
  version: "1.0.0"
  contact:
    name: ZhouZhou
    email: zhouruiyan@sansi.com
tags:
  - name: usersApi
    description: user 用户
paths:
  /api/users/login:
    post:
      summary: 登录
      tags: ["usersApi"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "userApiRequest.yaml#/user/schemas/userLogin"
      responses:
        "200":
          description: 操作成功
          content:
            application/json:
              schema:
                $ref: "userApiReturn.yaml#/user/schemas/userLogin"
        default:
          description: 意外出错
          content:
            application/json:
              schema:
                $ref: "defaultError.yaml#/error/schemas/errorMsg"
  /api/users:
    post:
      summary: 用户注册
      tags: ["usersApi"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "userApiRequest.yaml#/user/schemas/userObject"
      responses:
        "200":
          description: 操作成功
          content:
            application/json:
              schema:
                $ref: "userApiReturn.yaml#/user/schemas/userRegister"
        default:
          description: 意外出错
          content:
            application/json:
              schema:
                $ref: "defaultError.yaml#/error/schemas/errorMsg"
    get:
      description: 返回所有用户列表
      summary: 返回用户列表
      tags: ["usersApi"]
      responses:
        "200":
          description: 操作成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "userApiReturn.yaml#/user/schemas/userObject"
        default:
          description: 意外出错
          content:
            application/json:
              schema:
                $ref: "defaultError.yaml#/error/schemas/errorMsg"
  /api/users/{id}:
    get:
      summary: 根据用户ID查询用户信息
      tags: ["usersApi"]
      parameters:
        - name: id
          in: path
          description: URL路径参数,用户ID
          required: true
          schema:
            type: string
            example: 921921
      responses:
        "200":
          description: 操作成功
          content:
            application/json:
              schema:
                $ref: "userApiReturn.yaml#/user/schemas/userObject"
        default:
          description: 意外出错
          content:
            application/json:
              schema:
                $ref: "defaultError.yaml#/error/schemas/errorMsg"
    delete:
      summary: 根据用户ID删除用户信息
      tags: ["usersApi"]
      parameters:
        - name: id
          in: path
          description: URL路径参数,用户ID
          required: true
          schema:
            type: string
            example: 921921
      responses:
        "200":
          description: 操作成功
          content:
            application/json:
              schema:
                $ref: "userApiReturn.yaml#/user/schemas/oprCount"
        default:
          description: 意外出错
          content:
            application/json:
              schema:
                $ref: "defaultError.yaml#/error/schemas/errorMsg"
    patch:
      summary: 根据用户ID修改用户信息
      tags: ["usersApi"]
      parameters:
        - name: id
          in: path
          description: URL路径参数,用户ID
          required: true
          schema:
            type: string
            example: 921921
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "userApiRequest.yaml#/user/schemas/userObject"
      responses:
        "200":
          description: 操作成功
          content:
            application/json:
              schema:
                $ref: "userApiReturn.yaml#/user/schemas/userRegister"
        default:
          description: 意外出错
          content:
            application/json:
              schema:
                $ref: "defaultError.yaml#/error/schemas/errorMsg"


components:
  securitySchemes:
    api_Key:
      type: apiKey
      name: api_Key
      in: header

以下是openapi_userApi.yaml引用的文档：
defaultError.yaml

error:
  schemas:
    errorMsg:
      type: object
      properties:
        error:
          type: object
          properties:
            code: 
              type: integer
              example: 0
            message:
              type: string
            statusCode:
              type: integer
              example: 0
            name:
              type: string

userApiRequest.yaml

user:
  schemas:
    userLogin:
      type: object
      properties:
        login_name:
          type: string
          example: admin
        password:
          type: string
          example: admin1
      required:
        - login_name
        - password
    userObject:
      type: object
      properties:
        login_name:
          type: string
          example: admin
        user_name:
          type: string
          example: 周周
        user_mobile:
          type: string
          example: 18137748494
        user_email:
          type: string
          format: email
          example: 7738838@qq.com
        user_address:
          type: string
          example: 上海市闵行区
        password:
          type: string
          format: password
          example: admin1
      required:
        - login_name
        - user_name
        - user_mobile
        - password
    userList:
      type: object
      properties:
        user_name:
          type: string
          example: 周周
        user_mobile:
          type: string
          example: 18137748494

userApiReturn.yaml

user:
  schemas:
    userLogin:
      type: object
      properties:
        login_name:
          type: string
        id:
          type: string
      required:
        - login_name
        - id
    userRegister:
      type: object
      properties:
        id:
          type: string
        login_name:
          type: string
          example: admin
        password:
          type: string
          format: password 
        user_name:
          type: string
          example: 周周
        user_mobile:
          type: string
          example: 18137748494
        user_email:
          type: string
          format: email
          example: 7738838@qq.com
        user_address:
          type: string
          example: 上海市闵行区
      required:
        - id
        - login_name
        - user_name
        - user_mobile
    userObject:
      type: object
      properties:
        id:
          type: string
          format: UUID
        login_name:
          type: string
        user_name:
          type: string
        user_mobile:
          type: string
        user_email:
          type: string
          format: email
        user_address:
          type: string
    oprCount:
      type: object
      properties:
        count:
          type: integer
          format: int32
          example: 0