apifox和ts类型导出的最佳实践

相信很多小伙伴现在都已经进入了vue3 + ts的大时代。这样就会面临着ts类型维护的问题。本篇文章就提供给你一个可能的解决方案。

在我们编写ts类型的时候 ,有绝大部分其实都是基于对接口的入参和返回值类型的一个拓展。所以本篇文章就是教你如何快速的拿到接口相关的ts类型。

当然有个很重要的前提 后台要有接口文档。要是公司这东西都没有 也别上ts了 没必要。

apifox

我们的接口文档都是用apifox记录的,所以我也就基于apifox来讲述我的解决方案。

apifox的具体使用方式我这里就不做赘述了,不明白的可以移步Apifox 快速入门 | Apifox 帮助文档

当然你有什么用不明白的地方 也欢迎评论区交流。

在你启动apifox的客户端以后,apifox会在你本地启动一个,这样的服务http://127.0.0.1:4523/。我们通过这个服务访问这样的一个地址

bash 复制代码
http://localhost:4523/export/openapi?projectId=${你的项目id}&specialPurpose=openapi-generator

然后你就可以通过该 URL 自行使用 OpenAPI 规范 (中文版) (apifox.cn) 生成代码,以实现更个性化的需求。

ps:

这个地址你可以在这里看到

项目id在这里看到

OpenApi的数据格式转换

下面言归正传。我们先看一下这个url带给了我们什么样的数据。

我们把路径放入浏览器中就可以直接看到这样一个数据,可以大致的看出来他是对我们接口信息的一个json结构描述。下一步我们就要思考怎么样把这些数据转化为ts类型呢?

这一步就需要我们引入一个挺有名的依赖包 openapi-typescript。使用方式也很简单

javascript 复制代码
const fs = require(`fs`)
const axios = require(`axios`)
const path = require(`path`)
const openapiTS = import(`openapi-typescript`)
​
 const axiosData = axios
    .get(`http://localhost:4523/export/openapi?projectId=${projectId}&specialPurpose=openapi-generator`)
    .then(async response => {
      const { default: transform } = await openapiTS
      const typeDefinitions = await transform(response.data)
      const filePath = path.join(__dirname, `/src/types/apiFox/`, filename)
      fs.mkdirSync(path.dirname(filePath), { recursive: true })
      fs.writeFile(filePath, `/* eslint-disable */\n${typeDefinitions}`, err => {
        if (err) throw err
        console.log(`The file ${filename} has been saved!`)
      })
    })
    .catch(error => {
      console.error(error)
    })

这是段node代码。这段代码执行后 我们就会得到一个内容大概是这样的文件。

css 复制代码
/* eslint-disable */
export interface paths {
  '/literatureSearchHistory/add': {
    post: {
      requestBody?: {
        content: {
          'application/json': {
            query: string
          }
        }
      }
      responses: {
        200: {
          content: {
            'application/json': {
              data: {
                id: string
              }
              code: string
              message: string
            }
          }
        }
      }
    }
  }
}

我们可以在requestBody和responses看到很明显是有了ts类型了。下面我们只需要拿到这些类型就可以正常使用了。例如:

css 复制代码
type Response =  paths[`/selectAll`][`post`][`responses`][200][`content`][`application/json`][`data`]

虽然拿到了类型 但是这长的离谱。太不优雅了 让我们把他封装一下。

简化ts类型

scala 复制代码
import type { paths, components } from './main'
​
type Defined<T> = Exclude<T, undefined>
type ExtractType<Method extends keyof any, Path extends keyof Paths, Paths extends Record<string, any>> = {
  params: Paths[Path] extends { [K in Method]: any }
    ? Defined<Paths[Path][Method][`requestBody`]>[`content`][`application/json`]
    : unknown
  response: Paths[Path] extends { [K in Method]: any }
    ? Paths[Path][Method][`responses`][200][`content`][`application/json`][`data`]
    : unknown
}
​
//paths 与 components 是两个动态值。我们有新项目复制一下代码 修改动态值即可
export type PostType<Path extends keyof paths> = ExtractType<`post`, Path, paths>
export type GetType<Path extends keyof paths> = ExtractType<`get`, Path, paths>
export type DataModel<DataModelName extends keyof components[`schemas`]> = components[`schemas`][DataModelName]

使用的时候这样即可,是不是简单了很多呢。

go 复制代码
type Params = PostType<`接口路径`>[`params`]     //获取接口传参类型
type Response = PostType<`接口路径`>[`response`] //获取接口返回值类型
type Model = DataModel<`模型名称`>               //获取数据模型类型

结合我们api层的接口文件大概就是这样的

typescript 复制代码
const url = {
    getSystems: `/dsClass/querySystem` as const, //这个as const 必不可少
}
​
type Params = PostType<typeof url.getSystems>[`params`]    
type Response = PostType<typeof url.getSystems>[`response`]
function getSystems(params?:Params): Promise<Response> {
    return etlPost(url.getSystems, params)
  }
}
​
export {getSystems}

简单的应用到这里就完成了!

相关推荐
古夕几秒前
Vue3 + vue-query 的重复请求问题解决记录
前端·javascript·vue.js
不知名程序员第二部几秒前
前端-业务-架构
前端·javascript·代码规范
Bug生产工厂1 分钟前
React支付组件设计与封装:从基础组件到企业级解决方案
前端·react.js·typescript
小喷友1 分钟前
阶段三:进阶(Rust 高级特性)
前端·rust
华仔啊2 分钟前
面试官:请解释一下 JS 的 this 指向。别慌,看完这篇让你对答如流!
前端·javascript
Strayer2 分钟前
Tauri2.0打包构建报错
前端
小高0073 分钟前
💥💥💥前端“隐藏神技”:15 个高效却鲜为人知的 Web API 大起底
前端·javascript
flyliu4 分钟前
再再次去搞懂事件循环
前端·javascript
艾小码5 分钟前
还在拍脑袋估工时?3个技巧让你告别加班和延期!
前端·敏捷开发
UrbanJazzerati10 分钟前
前端入门:vh、padding、margin、outline、pointer-events
前端·面试