令#
基础用法
npx swagger-typescript-api generate -p http://localhost:5000/swagger/v1/swagger.json -o src/api -n index.ts
如果是用 bun，则把 npx 替换为 bunx
我测试之后发现使用最基础的这个命令，把全部接口都放在一个文件反而最好，其他的比如 --modular 模块化参数，经常会导致生成的代码报错。
可用命令行参数一览#
（整理自官方文档和 Fig.io）
-v, --version
输出当前工具版本
-p, --path <路径或 URL>
指定 Swagger/OpenAPI 文档的位置（本地路径或网络 URL）
-o, --output <目录路径>
输出生成文件的目录（默认 ./）
-n, --name <文件名>
指定输出 TypeScript API 文件名（默认 Api.ts）
-t, --templates <模板路径>
使用自定义 EJS 模板渲染生成逻辑
-d, --default-as-success
将 "default" 响应状态码也视为成功响应（一些 Swagger 用 default），默认 false
-r, --responses
生成额外的请求响应信息，包括出错类型的 typings
--union-enums
将所有枚举生成成 TypeScript 联合类型（T1 | T2 | TN）
--add-readonly
为生成的属性添加 readonly 修饰
--route-types
生成 API 路由相关的类型定义（如参数类型等）
--client / --no-client
是否生成 API 调用类（默认 --client），执行 --no-client 则只生成类型/数据层
--enum-names-as-values
使用 x-enumNames 的值作为 enum 值，而不仅是 key（默认 false）
--extract-request-params / --extract-request-body / --extract-response-body / --extract-response-error
将请求参数、请求体、响应体或错误响应提取成独立的数据契约类型
--modular
将 http client、数据契约、路由等代码拆分成多个文件（模块化）
--js
生成 JavaScript 模块和对应的 .d.ts 声明文件
--module-name-index <索引>
在模块化生成时决定从路径的哪个部分做索引分组
--module-name-first-tag
根据 API 的第一个 Tag 划分模块
网络设置：
--disableStrictSSL（禁用严格 SSL 验证）
--disableProxy（禁用代理）
HTTP 客户端选择：
--axios：生成以 axios 为底层客户端的请求代码
其他默认使用 fetch 或抽象
--unwrap-response-data
自动拆解响应中的 data 字段，直接返回内部数据
--disable-throw-on-error
遇到 response.ok !== true（HTTP 错误）时不抛异常（默认 false）
--single-http-client
生成 API 类时支持传入单一的 HTTP client 实例（默认 false）
输出控制：
--silent：只输出错误信息，其它静默
类型生成配置：
--default-response <Type>：响应 schema 为空时的默认类型
--type-prefix <前缀> / --type-suffix <后缀>：自定义数据模型名称前后缀
其他选项：
--clean-output：清理输出目录（注意会删除旧文件）
--api-class-name <类名>：指定生成的 API 类名称
--patch：修正 Swagger 源定义中的一些小错误
--debug：输出额外调试信息
--another-array-type：生成 Array<Type> 形式数组而非 Type[]（默认 false）
--sort-types：对字段和类型排序（默认 false）
--extract-enums：将所有枚举从 inline interface 中提取为独立的 TS enum
帮助命令：
--help, -h：列出所有命令帮助信息
在 Next.js 里使用例子#
以生成 StarBlog 的 API 接口为例
在 Next.js 项目中的目录结构是这样的：
其中 photo.ts 和 blog.ts 是生成的
lib
├─ api
│ └─ starblog
│ ├─ photo.ts
│ ├─ client.ts
│ └─ blog.ts
└─ source.ts
这里需要创建一个 client.ts 方便使用，代码
import { Api as BlogApi } from './blog';
import { Api as PhotoApi } from './photo';
// 直接导出类型
export type { Post, Photo, FeaturedPost, PostListApiResponse, PostApiResponsePaged } from './blog';
export type { PhotoApiResponsePaged } from './photo';
/**
* 获取API基础URL
* @param baseUrl 可选的基础URL
* @returns 最终的API基础URL
*/
function getApiBaseUrl(baseUrl?: string): string {
// 在服务端环境中，优先使用服务端API URL
return typeof window === 'undefined'
? (process.env.API_BASE_URL || baseUrl || process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:5000')
: (baseUrl || process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:5000');
}
/**
* 创建博客API客户端
* @param baseUrl 可选的基础URL
* @returns 博客API实例
*/
export function createBlogApi(baseUrl?: string): BlogApi<unknown> {
return new BlogApi({
baseUrl: getApiBaseUrl(baseUrl),
customFetch: fetch,
});
}
/**
* 创建照片API客户端
* @param baseUrl 可选的基础URL
* @returns 照片API实例
*/
export function createPhotoApi(baseUrl?: string): PhotoApi<unknown> {
return new PhotoApi({
baseUrl: getApiBaseUrl(baseUrl),
customFetch: fetch,
});
}
// 为了向后兼容，保留原有的函数名
export const createStarBlogApiClient = createBlogApi;
在页面里请求
import {createBlogApi, createPhotoApi, Post, Photo} from '@/lib/api/starblog/client';
/**
* 获取推荐博客文章
*/
async function getFeaturedPosts(): Promise<Post[]> {
try {
const blogApi = createBlogApi();
const response = await blogApi.api.blogFeaturedList();
if (response.data?.successful && response.data?.data) {
return response.data.data;
}
return [];
} catch (error) {
console.error('获取推荐文章失败:', error);
return [];
}
}
/**
* 获取摄影作品
*/
async function getPhotos(): Promise<Photo[]> {
try {
const photoApi = createPhotoApi();
console.log('正在获取摄影作品，API基础URL:', process.env.NEXT_PUBLIC_API_BASE_URL);
const response = await photoApi.api.photoList({page: 1, pageSize: 8});
console.log('摄影作品API响应:', response.data);
if (response.data?.successful && response.data?.data) {
console.log('获取到的摄影作品数量:', response.data.data.length);
response.data.data.forEach((photo, index) => {
console.log(`摄影作品 ${index + 1}:`, {
id: photo.id,
title: photo.title,
filePath: photo.filePath,
fullUrl: `${process.env.NEXT_PUBLIC_API_BASE_URL}/media/photography/${photo.filePath}`
});
});
return response.data.data;
}
console.warn('摄影作品API响应不成功或无数据');
return [];
} catch (error) {
console.error('获取摄影作品失败:', error);
return [];
}
}
export default async function HomePage() {
// 在服务端并行获取数据
const [posts, photos] = await Promise.all([
getPosts(),
getPhotos()
]);
return (
<div>
<BlogPosts
posts={posts}
baseUrl={process.env.NEXT_PUBLIC_API_BASE_URL || ''}
/>
<PhotoGallery
photos={photos}
baseUrl={process.env.NEXT_PUBLIC_API_BASE_URL || ''}
/>
</div>
)
