Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/openapi-ui/openapi-ts-request

Swagger2/OpenAPI3/Apifox to TS/JS, request client, mock service, enum, react-query, type field label, JSON Schemas; 根据 Swagger2/OpenAPI3/Apifox 生成 TypeScript/JavaScript, 客户端请求函数(支持任意客户端), 模拟请求响应服务, 枚举和枚举翻译, react-query, 类型的字段翻译, JSON Schemas定义, 欢迎提功能请求
https://github.com/openapi-ui/openapi-ts-request

openapi-axios openapi-fetch openapi-taro openapi-typescript-generator openapi-typescript-request openapi-uniapp

Last synced: 16 days ago
JSON representation

Swagger2/OpenAPI3/Apifox to TS/JS, request client, mock service, enum, react-query, type field label, JSON Schemas; 根据 Swagger2/OpenAPI3/Apifox 生成 TypeScript/JavaScript, 客户端请求函数(支持任意客户端), 模拟请求响应服务, 枚举和枚举翻译, react-query, 类型的字段翻译, JSON Schemas定义, 欢迎提功能请求

Awesome Lists containing this project

README 

        
## Introduce



[![GitHub Repo stars](https://img.shields.io/github/stars/openapi-ui/openapi-ts-request?style=social)](https://github.com/openapi-ui/openapi-ts-request) [![npm (scoped)](https://img.shields.io/npm/v/openapi-ts-request)](https://www.npmjs.com/package/openapi-ts-request) ![GitHub tag](https://img.shields.io/github/v/tag/openapi-ui/openapi-ts-request?include_prereleases)



English | 简体中文



based on [Swagger2/OpenAPI3/Apifox](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) specification Generate



- TypeScript/JavaScript

- request client(support any client)

- request mock service

- enum and enum translation

- react-query/vue-query

- type field label

- JSON Schemas

- Apifox Config



docs：[use docs](https://github.com/openapi-ui/openapi-ts-request/issues/100)



## Features



- support Swagger2.0/OpenAPI/Apifox 3.0,3.1 specification

- generate TypeScript/JavaScript, reuquest client(support any client), request mock service, enum and enum translation, react-query/vue-query, type field label, JSON Schemas

- support work with npx, CLI, Nodejs

- support custom request function, Fetch、Axios、[UniApp-request](https://github.com/openapi-ui/openapi-ts-request/issues/46)、Taro-Request、Node.js、XHR client available

- support filter generate result by tags

- support JSON/YAML specification

- support translate chinese tag name to english tag name

- support direct configuration of `apifox` `token` and `projectId` direct generation



## Usage



```bash

# npm

npm i openapi-ts-request --save-dev



# pnpm

pnpm i openapi-ts-request -D

```



### CosmiConfig



create `openapi-ts-request.config.ts` file in the project root directory



> the config file also supports **_.openapi-ts-request.ts_**, **_openapi-ts-request.config.cjs_** format, reference [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#cosmiconfig)



```ts

import type { GenerateServiceProps } from 'openapi-ts-request';



export default {

  // schemaPath: './openapi.json', // local openapi file

  // serversPath: './src/apis', // interface storage path

  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',

} as GenerateServiceProps;

```



support passing in array config for generate



```ts

import type { GenerateServiceProps } from 'openapi-ts-request';



export default [

  {

    schemaPath: 'http://app.swagger.io/v2/swagger.json',

    serversPath: './src/apis/app',

  },

  {

    schemaPath: 'http://auth.swagger.io/v2/swagger.json',

    serversPath: './src/apis/auth',

  },

] as GenerateServiceProps[];

```



add the command in `script` of `package.json`: `"openapi": "openapi-ts",`



run:



```bash

npm run openapi

```



run:



```bash

src/apis/index.ts #interface entry file

src/apis/types.ts #type definition file

src/apis/app #app interface

```



```typescript

// src/apis/pet.ts

/* eslint-disable */

// @ts-ignore

import request from 'axios';



import * as API from './types';



/** Update an existing pet PUT /pet */

export async function updatePet({

  body,

  options,

}: {

  body: API.Pet;

  options?: { [key: string]: unknown };

}) {

  return request(`/pet`, {

    method: 'PUT',

    headers: {

      'Content-Type': 'application/json',

    },

    data: body,

    ...(options || {}),

  });

}



// ... more interfaces

```



### JS



create a new `openapi-ts-request.config.js` file in any directory `xxx/xxx`



```ts

const { generateService } = require('openapi-ts-request');



generateService({

  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',

  serversPath: './apis',

});

```



add the command in `script` of `package.json`: `"openapi": "node xxx/xxx/openapi-ts-request.config.js"`



run:



```bash

npm run openapi

```



### TS



create a new `openapi-ts-request.config.ts` file in any directory `xxx/xxx`



```ts

const { generateService } = require('openapi-ts-request');



generateService({

  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',

  serversPath: './apis',

});

```



add the command in `script` of `package.json`: `"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",`



run:



```bash

npm run openapi

```



### NPX



```bash

# npm

npx --package=openapi-ts-request -- openapi -i ./openapi.json -o ./apis

npx --package=openapi-ts-request -- openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis



# pnpm

pnpm --package=openapi-ts-request@latest dlx openapi -i ./openapi.json -o ./apis

pnpm --package=openapi-ts-request@latest dlx openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis

```



### CLI



```

npm i openapi-ts-request -g

```



```

$ openapi --help



  Usage: openapi [options]



  Options:

    -V, --version                       output the version number

    -i, --input                 OpenAPI specification, can be a path, url

    -o, --output                output directory

    -cfn, --configFileName      config file name

    -cfp, --configFilePath      config file path

    -u, --uniqueKey             unique key

    --requestLibPath            custom request lib path, for example: "@/request", "node-fetch" (default: "axios")

    -f, --full                 full replacement (default: true)

    --enableLogging            open the log (default: false)

    --priorityRule              priority rule, include/exclude/both (default: "include")

    --includeTags <(string|RegExp)[]>   generate code from include tags

    --includePaths <(string|RegExp)[]>  generate code from include paths

    --excludeTags <(string|RegExp)[]>   generate code from exclude tags

    --excludePaths <(string|RegExp)[]>  generate code from exclude paths

    --requestOptionsType        custom request method options parameter type (default: "{ [key: string]: unknown }")

    --requestImportStatement    custom request import statement, for example: "const request = require('@/request')"

    --apiPrefix                 custom the prefix of the api path, for example: "api"(variable), "'api'"(string)

    --isGenReactQuery          generate react-query (default: false)

    --reactQueryMode            react-query mode, react/vue (default: "react")

    --isGenJavaScript          generate JavaScript (default: false)

    --isDisplayTypeLabel       generate label matching type field (default: false)

    --isGenJsonSchemas         generate JSON Schemas (default: false)

    --mockFolder                mock file path, for example: './mocks'

    --authorization             docs authorization

    --nullable                 null instead of optional (default: false)

    --isTranslateToEnglishTag  translate chinese tag name to english tag name (default: false)

    --isOnlyGenTypeScriptType  only generate typescript type (default: false)

    --isCamelCase              camelCase naming of controller files and request client (default: true)

    --isSupportParseEnumDesc   parse enum description to generate enum label (default: false)

    -h, --help                          display help for command

```



run:



```bash

openapi -i ./spec.json -o ./apis

```



## Parameter



| props | required | type | default | remark |

| --- | --- | --- | --- | --- |

| schemaPath | yes | string | - | Swagger2/OpenAPI3 URL |

| serversPath | no | string | './src/apis' | the folder path for the run results |

| requestLibPath | no | string | 'axios' | custom request lib path, for example: '@/request', 'node-fetch' |

| full | no | boolean | true | full replacement |

| enableLogging | no | boolean | false | open the log |

| priorityRule | no | string | 'include' | priority rule, include/exclude/both |

| includeTags | no | (string\|RegExp)[] | - | generate code from include tags, priorityRule=include required |

| includePaths | no | (string\|RegExp)[] | - | generate code from include paths |

| excludeTags | no | (string\|RegExp)[] | - | generate code from exclude tags |

| excludePaths | no | (string\|RegExp)[] | - | generate code from exclude paths |

| requestOptionsType | no | string | '{ [key: string]: unknown }' | custom request method options parameter type |

| requestImportStatement | no | string | - | custom request import statement, for example: "const request = require('@/request')" |

| apiPrefix | no | string | - | custom the prefix of the api path, for example: 'api'(variable), "'api'"(string) |

| isGenReactQuery | no | boolean | false | generate react-query |

| reactQueryMode | no | string | 'react' | react-query mode, react/vue |

| isGenJavaScript | no | boolean | false | generate JavaScript |

| isDisplayTypeLabel | no | boolean | false | generate label matching type field |

| isGenJsonSchemas | no | boolean | false | generate JSON Schemas |

| mockFolder | no | string | - | mock file path, for example: './mocks' |

| authorization | no | string | - | docs authorization |

| apifoxConfig | no | [Apifox Config](#Apifox-Config) | - | apifox configs |

| nullable | no | boolean | false | null instead of optional |

| isTranslateToEnglishTag | no | boolean | false | translate chinese tag name to english tag name |

| isOnlyGenTypeScriptType | no | boolean | false | only generate typescript type |

| isCamelCase | no | boolean | true | camelCase naming of controller files and request client |

| isSupportParseEnumDesc | no | boolean | false | parse enum description to generate enum label, format example: `UserRole:User(Normal User)=0,Agent(Agent)=1,Admin(Administrator)=2` |

| hook | no | [Custom Hook](#Custom-Hook) | - | custom hook |



## Custom Hook



| props | type | remark |

| --- | --- | --- |

| afterOpenApiDataInited | (openAPIData: OpenAPIObject) => OpenAPIObject | custom OpenAPI data |

| customFunctionName | (data: APIDataType) => string | custom request client function name |

| customTypeName | (data: APIDataType) => string | custom type name |

| customClassName | (tagName: string) => string | custom tag name |

| customType | ({
schemaObject: SchemaObject \| ReferenceObject,
namespace: string,
originGetType:(schemaObject: SchemaObject \| ReferenceObject, namespace: string, schemas?: ComponentsObject['schemas']) => string,
schemas?: ComponentsObject['schemas'],
}) => string | custom type 
 _returning a non-string will use the default method to get the type_ |

| customFileNames | (
operationObject: OperationObject,
apiPath: string,
apiMethod: string,
) => string[] | custom generate request client controller file name, can return multiple: generate multiple files. 
 _if the return value is empty, the default getFileNames is used_ |

| customTemplates | {
[TypescriptFileType.serviceController]?: (item: T, context: U) => string;
} | custom template, details see source code |



## Apifox-Config



| attribute | type | description | required |

| --- | --- | --- | --- |

| projectId | string | project id | true |

| apifoxToken | string | [get](https://docs.apifox.com/doc-5723694) | true |

| local | string | language(default:zh-CN) | false |

| apifoxVersion | string | default: 2024-03-28, [current apifox version](https://api.apifox.com/v1/versions) | false |

| includeTags | \* or string[] | default: \* | false |

| excludeTags | string[] | default: [] | false |

| oasVersion | string | specify the version of the OpenAPI specification used for export, can have values such as "2.0", "3.0" or "3.1" | '3.0' |

| exportFormat | string | specify the format of the exported OpenAPI file, can have values such as 'JSON' or 'YAML' | 'JSON' |

| includeApifoxExtensionProperties | boolean | specify whether to include the OpenAPI specification extension fields `x-apifox` | false |

| addFoldersToTags | boolean | specify whether to include the directory name of the interface in the tag field | false |



## JSON Schemas



- default generate JSON Schemas based on [components.schemas](https://spec.openapis.org/oas/latest.html#components-object), JSON Schemas corresponding to [paths](https://spec.openapis.org/oas/latest.html#paths-object) currently need to be parsed by yourself

- provide a schema parsing function to fill the references of `$ref` and `$allOf` into `current schema`



```ts

export declare function patchSchema(

  schema: ISchemaObject,

  schemas: ComponentsObject['schemas']

): T;

```



## Mock



currently using [mockjs](http://mockjs.com) to generate mock data, the mocks file startup needs to rely on [@umijs/server](https://umijs.org/docs/guides/mock), we will look for other solutions later to achieve a better mock experience



## Adapt to uniapp



it is recommended to use a custom request function to adapt to uniapp. you can also use the `@uni-helper/axios-adapter` adapter. for details, see [【use docs 2.2】](https://github.com/openapi-ui/openapi-ts-request/issues/100)



## Notes on Upgrading Older Versions



- Current naming convention changes

- Incremental changes have been made to the current version and will not affect previous versions.

- The `openapi-ts` command can be deprecated to use `openapi`



### The configuration follows the naming convention of the old version as follows



```typescript

import type { APIDataType } from 'openapi-ts-request/dist/generator/type';

import {

  genDefaultFunctionName,

  resolveFunctionName,

  stripDot,

} from 'openapi-ts-request/dist/generator/util';



export default {

  hook: {

    customFunctionName(data: APIDataType, prefix: string) {

      if (data.operationId)

        return resolveFunctionName(stripDot(data.operationId), data.method);

      return data.method + genDefaultFunctionName(data.path, prefix);

    },

  },

};

```



## Contribute



### Development Environment



- node 18+

- pnpm 9+



### Submit Pull Request



1. learn [Pull Request]("https://help.github.com/articles/using-pull-requests") specification

2. fork this repository

3. create a new branch to modify the code：`git checkout -b my-branch main`

4. make sure your code passes all test cases (new functional test cases need to be added for new features)：`pnpm test`

5. create a changeset file using the command：`pnpm changeset`

6. submit your changes using commit (must follow commitlint specification)

7. submit Pull Request



## Thanks



- [openapi2typescript](https://github.com/chenshuai2144/openapi2typescript)