Project Icon

swagger-axios-codegen

将Swagger API文档生成TypeScript代码的开源工具

swagger-axios-codegen是一款开源工具,用于将Swagger API文档生成TypeScript代码,并通过Axios进行HTTP请求。它支持自定义请求实例、多文件模式和类转换等高级功能,适合需要与Swagger兼容的开发者。该工具提供灵活的配置选项,开发者可以根据需要调整生成代码的结构,以优化代码管理。项目对PR和问题反馈持欢迎态度,持续改进用户体验。

swagger-axios-codegen

一个使用了axios和typescript的swagger客户端

NpmVersionnpm open issues

< v0.16 需要 node > v10.0.0

>= v0.16 需要 node >= v16

它将始终解析 axios.response.data 或者使用 Promise 拒绝 axios.error

支持其他类似 axios 的库,例如 Fly.js,需要设置ISwaggerOptions.useCustomerRequestInstance = true

ES6版本是通过调用TypeScript生成的

欢迎PR和提交问题

顺便说一句,你可以通过 Star 支持这个项目 ⭐️ ⭐️ ⭐️ ⭐️ ⭐️

示例

更新日志

贡献指南

快速开始

  yarn add swagger-axios-codegen

export interface ISwaggerOptions {
  serviceNameSuffix?: string
  enumNamePrefix?: string
  methodNameMode?: 'operationId' | 'path' | 'shortOperationId' | ((reqProps: IRequestMethod) => string)
  classNameMode?: 'parentPath' | 'normal' | ((path: string, method: string, reqProps:IRequestMethod) => string)
  /** 仅在 classNameMode='parentPath' 时生效 */
  pathClassNameDefaultName?: string
  outputDir?: string
  fileName?: string
  remoteUrl?: string
  source?: any
  useStaticMethod?: boolean | undefined
  useCustomerRequestInstance?: boolean | undefined
  include?: Array<string | IInclude>
  /** 包含在过滤过程中未包含的类型 **/
  includeTypes?: Array<string>
  format?: (s: string) => string
  /** 匹配 with tsconfig */
  strictNullChecks?: boolean | undefined
  /** definition Class mode */
  modelMode?: 'class' | 'interface'
  /** 使用 class-transformer 转换结果 */
  useClassTransformer?: boolean
  /** 强制指定 swagger 或 openAPI 版本 */
  openApi?: string | undefined
  /** 扩展文件 URL。它将插入服务方法前 */
  extendDefinitionFile?: string | undefined
  /** 标记泛型类型 */
  extendGenericType?: string[] | undefined
  /** 生成验证模型(仅限类模式) */
  generateValidationModel?: boolean
  /** 拆分请求服务。不能与 sharedServiceOptions 一起使用 */
  multipleFileMode?: boolean | undefined
  /** URL 前缀过滤器 */
  urlFilters?: string[] | null | undefined
  /** 共享服务选项到多个服务。不能与 MultipleFileMode 一起使用 */
  sharedServiceOptions?: boolean | undefined
  /** 是否使用头参数 */
  useHeaderParameters?: boolean
}

const defaultOptions: ISwaggerOptions = {
  serviceNameSuffix: 'Service',
  enumNamePrefix: 'Enum',
  methodNameMode: 'operationId',
  classNameMode: 'normal',
  pathClassNameDefaultName: 'Global',
  outputDir: './service',
  fileName: 'index.ts',
  useStaticMethod: true,
  useCustomerRequestInstance: false,
  include: [],
  strictNullChecks: true,
  /** definition Class mode,自动使用 interface 模式简化代码 */
  modelMode: 'interface',
  useClassTransformer: false
}

使用本地 swagger api json


const { codegen } = require('swagger-axios-codegen')
codegen({
  methodNameMode: 'operationId',
  source: require('./swagger.json')
})


使用远程 swagger api json


const { codegen } = require('swagger-axios-codegen')
codegen({
  methodNameMode: 'operationId',
  remoteUrl:'你远程的 URL'
})


使用静态方法

codegen({
    methodNameMode: 'operationId',
    remoteUrl: 'http://localhost:22742/swagger/v1/swagger.json',
    outputDir: '.',
    useStaticMethod: true
});


import { UserService } from './service'
const userService = new UserService()
await userService.GetAll();


import { UserService } from './service'

await UserService.GetAll();

使用自定义 axios 实例

import axios from 'axios'
import { serviceOptions } from './service'
const instance = axios.create({
  baseURL: 'https://some-domain.com/api/',
  timeout: 1000,
  headers: {'X-Custom-Header': 'foobar'}
});

serviceOptions.axios = instance

使用其他库

import YourLib from '<Your lib>'
import { serviceOptions } from './service'

serviceOptions.axios = YourLib

过滤服务和方法

通过 multimatch 使用 'include' 设置进行筛选

codegen({
  methodNameMode: 'path',
  source: require('../swagger.json'),
  outputDir: './swagger/services',
  include: [
    '*',
    // 'Products*',
    '!Products',
    { 'User': ['*', '!history'] },
  ]
})

如果你的服务名称中使用了特殊字符(即第一个标签),你必须假设它们已经转义。

例如,服务名称为 MyApp.FirstModule.Products, MyApp.FirstModule.Customers, MyApp.SecondModule.Orders

// API
"paths": {
  "/Products/Get": {
    "post": {
      "tags": [
        "MyApp.FirstModule.Products"
      ],
      "operationId": "Get",
// Codegen config
codegen({
  methodNameMode: 'path',
  source: require('../swagger.json'),
  outputDir: './swagger/services',
  include: ['MyAppFirstModule*'] // 只有Products和Customers会被包含。如你所见,点被解释为合同名称。
})

使用 class-transformer 转换结果

这对于想将日期转换为实际日期对象的用户很有帮助。Swagger 可以为不同类型定义字符串格式。其中两个格式是 datedate-time

如果 class-transformer 启用并且字符串上设置了格式,结果字符串将转换为 Date 实例。

// swagger.json

{
  "ObjectWithDate": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}

const { codegen } = require('swagger-axios-codegen')
codegen({
  methodNameMode: 'operationId',
  source:require('./swagger.json'),
  useClassTransformer: true,
})

生成类:

export class ObjectWithDate {
  @Expose()
  @Type(() => Date)
  public date: Date;
}

服务方法将转换json响应并返回该类的实例

使用验证模型

codegen({
    ...
    modelMode: 'class',
    generateValidationModel: true
});

上述选项结合类模型模式允许呈现模型验证规则。结果如下所示:

export class FooFormVm {
  'name'?: string;
  'description'?: string;
 
  constructor(data: undefined | any = {}) {
    this['name'] = data['name'];
    this['description'] = data['description'];
  }
 
  public static validationModel = {
    name: { required: true, maxLength: 50 },
    description: { maxLength: 250 },
  };
}

因此你可以在应用程序中使用验证模型:

function isRequired(vm: any, fieldName: string): boolean {
  return (vm && vm[fieldName] && vm[fieldName].required === true);
}
function maxLength(vm: any, fieldName: string): number {
  return (vm && vm[fieldName] && vm[fieldName].maxLength ? vm[fieldName].maxLength : 4000);
}

现在你可以使用这些函数

var required = isRequired(FooFormVm.validationModel, 'name');
var maxLength = maxLength(FooFormVm.validationModel, 'description');

目前只支持两个规则 - requiredmaxLength

一些解决方案

1.引用参数

参见 #53,使用包 json-schema-ref-parser

2.与 Microservice Gateway 一起使用

const {codegen} = require('swagger-axios-codegen')
const axios = require('axios')
// 主机地址
const host = 'http://your-host-name'

// 
const modules = [
  ...
]

axios.get(`${host}/swagger-resources`).then(async ({data}) => {
  console.warn('code', host)
  for (let n of data) {
    if (modules.includes(n.name)) {
      try {
        await codegen({
          remoteUrl: `${host}${n.url}`,
          methodNameMode: 'operationId',
          modelMode: 'interface',
          strictNullChecks: false,
          outputDir: './services',
          fileName: `${n.name}.ts`,
          sharedServiceOptions: true,
          extendDefinitionFile: './customerDefinition.ts',
        })
      } catch (e) {
        console.log(`${n.name} 服务错误`, e.message)
      }
    }
  }
})

项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台,能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐,Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持,能够阅读和理解用户上传的文件内容,解析网页信息,并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题,Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型,免费访问各种图像生成与AI训练工具,从Stable Diffusion等基础模型开始,轻松实现创新图像生成。体验前沿的AI技术,推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器,它将改变您观看视频的方式!SubCat结合了先进的人工智能技术,为您提供即时视频字幕翻译,无论是本地视频还是网络流媒体,让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台,利用前沿AI技术,为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图,再到文案生成,美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号