🥱还在手撸接口?来整个接口请求生成器吧!(上)

我是紫菜苔
1,320 阅读5分钟

这是我参与8月更文挑战的第7天，活动详情查看：8月更文挑战

背景

在现在前后端分离的工程中,前端常常逃不过的一个工作量就是需要把一堆API接口进行整理,配置到项目中.而且在这其中很包含着API的修改,更新,这些工作都会耗费大量的时间,更不用说偶尔的手残导致的问题更是容易让人绝望.

那么我们的问题就是,我们有必要一定要手写API么?,有没有办法可以自动的生成相关的结构配置文件?这些都是我们需要解决的问题.

Swagger

今天首先要提到的就是Swagger,现在估计很多的项目都会使用Swagger来生成后端接口文档.Swagger的好处就是不管后端接口结构如何,都可以一种标准的方式来生成一种一致的标准配置数据.

image.png

既然Swagger生成了一致的配置数据,那我们应该如何利用他,我们先来看看Swagger的界面

image.png

Swagger把我们所有开放的接口以统一的结构进行了显示,我们可以看到接口的地址,需要的参数,以及请求的类型和返回值相关信息.

Swagger也提供了数据化的显示

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
  description: "Everything about your Pets"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
- name: "store"
  description: "Access to Petstore orders"
- name: "user"
  description: "Operations about user"
  externalDocs:
    description: "Find out more about our store"
    url: "http://swagger.io"
schemes:
- "https"
- "http"
paths:
  /pet:
    post:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
      responses:
        "405":
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
   ...

可以看到这个yaml文件中的数据就是我们想要的东西,我们可以从这里取出有哪些结构,每个接口的请求类型,请求地址等信息,如果有了这些信息我们也可以用来生成请求需要的相关代码.

但是如何获得这些信息呢,一个是通过Swagger文档的导出功能生成yaml或者json文件,如果文档更新这就需要我们重新来生成导出.还有一种就是通过Swagger API接口来获取接口信息.

http[s]://s[wagger地址]/[v2|v3]/api-docs

swagger有一个api-docs接口,通过这个接口我们就可以获取相应JSON结构的接口数据,这样我们需要获取最新的接口数据时直接调用这个接口即可,需要注意的Swagger的版本是否正确.

数据结构

我们先来看看Swagger API返回的数据哪些对我们有用

  • host
  • basePath
  • tags
  • paths

host是当前服务的域名或地址,如果是微服务那么basePath会是相应的公共路径,tags里会有一些手动标记的描述信息,而paths中是我们主要的接口信息.

我们再来看看一下paths中又有哪些数据项

...
paths:{
    [path]:{
        [method]:{
            tags:[...],
            summary:...,
            description: ...,
            operationId: ...,
            produces: [...],
            responses: ...,
            parameters: ...,
            deprecated: false
        }
    }
}
...

paths是一个对象,他的key就是path是对应请求的地址路径,对应的下一级也是一个对象,这里的key会是对应接口的method请求方式,它的值也是对象,其中summary一般是一些描述信息,parameters是请求参数.

我们可以看到我们拥有

  • host
  • basePath
  • path
  • method

我们已经可以构建出我们需要的请求地址,以及请求方式.

生成配置

在我们准备生成接口请求文件前,我们先来准备一些配置文件

module.exports = {
  "gateway": "http://gateway.xxx.com",
  "apiVersion:": "v2",
  "controllerDir": {
    "alias": "../controller",   // 控制器目录名别
    "path": "./src/controller"  // 控制器目录路径
  },
  "serviceDir": {
    "alias": "@/http/services", // 服务目录名别
    "path": "./src/services" // 服务目录名别
  },
  services:{
    "service-1":"service-1",
    "service-2":"service-2",
    "service-3":"service-3"
  }
}
  • gateway

我们需要通过gateway来设置我们需要请求的Swagger API地址

  • apiVersion

指定对应的Swagger版本

  • services

如果是使用单服务其实不需要这个配置,这里是假设我们使用了微服务,这里配置的是对应的每个服务地址和名称

  • controllerDir

controller文件生成目录

  • serviceDir

service文件生成目录

因为我的网络请求使用了@gopowerteam/http-request这个库,这个库的请求需要有一个用于配置接口的controller文件,以及一个发送请求的service文件,所有我需要设置目录来生成我需要的对应的文件.

可以看到我们的计划就是,希望通过Swagger API获取接口信息,然后通过接口数据来生成对应的controller文件和service文件,这样我们在业务代码中就可以不再管理具体接口地址的配置,直接调用service文件来发送网络请求.

const userService = new UserService()

userService.login(new RequestParams()).subscribe({
    next: data => {
        console.log(data)
    }
})

之后的部分我们接着来看日和来自动生成相关的请求配置代码.

源码地址: github

如果您觉得这篇文章有帮助到您的的话不妨🍉关注+点赞+收藏+评论+转发🍉支持一下哟~~😛

avatar
文章
阅读
粉丝