Wasp 如何为自定义 API 添加 Swagger UI 文档页并在线测试端点-北京尧图网络

Wasp 如何为自定义 API 添加 Swagger UI 文档页并在线测试端点【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp如果你的 Wasp 应用里定义了一些自定义api例如GET /status、POST /users想让 API 的调用者在一个网页上看到所有端点的文档并直接在线发送请求Wasp 官方提供了用swagger-jsdocswagger-ui-express给应用挂载 Swagger UI 的集成方案。按官方指南操作后启动应用访问http://localhost:3001/api-docs就能看到带探索explorer功能的文档页可以在页面上填写参数、携带 JWT token 并直接调用你的端点。该指南标注的已验证版本为 Wasp 0.24、swagger-jsdoc6、swagger-ui-express5。前置条件是已经有一个 Wasp 应用并且其中至少声明了自定义 API。Wasp 的自定义 API 通过api构造器在main.wasp.ts的spec中声明实现为一个接收req、res、context三个参数的 Node.js 函数详见自定义 HTTP API 文档。1. 安装依赖在项目根目录安装运行期依赖和类型声明npm install swagger-jsdoc swagger-ui-express npm install --save-dev types/swagger-jsdoc types/swagger-ui-express2. 在 main.wasp.ts 中声明 apiNamespaceSwagger UI 页面本身也是一个 HTTP 端点集合Wasp 通过apiNamespace为指定路径下的所有 API 统一应用一个middlewareConfigFn。在spec中加入/api-docs命名空间并指向你稍后创建的swaggerMiddlewareimport { api, apiNamespace, app } from wasp.sh/spec import { getStatus } from ./src/apis with { type: ref } import { swaggerMiddleware } from ./src/swagger-ui with { type: ref } export default app({ name: MyApp, wasp: { version: ^0.24.0 }, title: my-app, head: [link relicon href/favicon.ico /], spec: [ apiNamespace(/api-docs, { middlewareConfigFn: swaggerMiddleware }), api(GET, /status, getStatus, { auth: false }), ], })apiNamespace的中间件会安装到路由级别等价于 Express 的router.use(/api-docs, ...)只作用于该路径下的请求不影响全局中间件全局/路径级中间件机制见中间件配置文档。3. 创建 spec 生成脚本 scripts/generate-swagger.js这一步是 Wasp 集成与直接用swagger-ui-express的关键差异swagger-jsdoc会在运行时扫描源码文件而src/目录不包含在生产 Docker 镜像里所以需要先离线把 JSDoc 注释扫描出来生成一个会被打包进服务器的 TypeScript 模块。创建scripts/generate-swagger.jsimport swaggerJsdoc from swagger-jsdoc; import { writeFileSync } from fs; const spec swaggerJsdoc({ definition: { openapi: 3.0.0, info: { title: My API, version: 1.0.0, description: API documentation for my Wasp application, contact: { name: API Support, url: https://example.com, email: supportexample.com, }, }, components: { securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT, description: Enter your JWT token in the format: Bearer {token}, }, }, }, security: [{ bearerAuth: [] }], }, apis: [./src/**/*.ts, !./src/swaggerSpec.ts], }); writeFileSync( ./src/swaggerSpec.ts, const swaggerSpec ${JSON.stringify(spec, null, 2)} as const;\nexport default swaggerSpec;\n, ); console.log(swaggerSpec.ts generated);脚本里的definition需要按你的应用改写info中的 title、version、description 和 contact 是文档页展示的元信息url/email等值应替换为你自己的apis数组表示扫描./src下所有.ts文件并排除生成物./src/swaggerSpec.ts本身。每当新增或修改了 JSDoc 注释重新运行一次生成脚本node scripts/generate-swagger.js成功后会生成src/swaggerSpec.ts该文件会被打包进服务器在开发和生产环境都能使用。由于它是生成文件指南建议把它加入.gitignore。4. 创建 Swagger 中间件 src/swagger-ui.ts创建src/swagger-ui.ts导出swaggerMiddleware它做三件事调整helmet配置关闭 contentSecurityPolicy 和 hsts否则 Swagger UI 页面的静态资源会被拦截、挂载swaggerUi.serve提供静态资源、挂载swaggerUi.setup提供文档页和swagger.jsonimport * as express from express; import helmet from helmet; import swaggerUi from swagger-ui-express; import { env, MiddlewareConfigFn } from wasp/server; import baseSwaggerDoc from ./swaggerSpec; const swaggerDoc { ...baseSwaggerDoc, servers: [{ url: env.WASP_SERVER_URL, description: API server }], }; export const swaggerMiddleware: MiddlewareConfigFn (middlewareConfig) { middlewareConfig.delete(helmet); middlewareConfig.set( helmet, helmet({ contentSecurityPolicy: false, hsts: false, }), ); swaggerUi.serve.forEach((handler, i) { middlewareConfig.set(swaggerServe${i}, handler); }); middlewareConfig.set( swaggerSetup, ( req: express.Request, res: express.Response, next: express.NextFunction, ) { return swaggerUi.setup(swaggerDoc, { explorer: true, customCss: .swagger-ui .topbar { display: none }, swaggerOptions: { persistAuthorization: true, url: /api-docs/swagger.json, }, })(req, res, next); }, ); return middlewareConfig; };几个关键配置servers使用wasp/server导出的env.WASP_SERVER_URL作为 API 服务器地址文档页上的请求会指向该地址部署环境设置该变量即可生效explorer: true开启端点探索功能这是在线测试端点的开关url: /api-docs/swagger.json指定 Swagger UI 从哪个地址拉取 spec与/api-docs命名空间路径一致persistAuthorization: true让页面上填写的授权信息在刷新后保留配合第 3 步脚本里声明的bearerAuthJWTsecurityScheme你可以在页面上填入Bearer token后连续测试需要认证的端点。helmet的修改只发生在middlewareConfigFn返回的配置里即只作用于/api-docs路径不影响应用其他请求的默认安全头。5. 为 API 实现添加 JSDoc 注释文档内容来自写在 API 实现函数上方的swaggerJSDoc 注释。以指南中的getStatus为例import { GetStatus } from wasp/server/api; /** * swagger * /status: * get: * summary: Get API status * description: Returns the current status of the API * tags: * - Status * security: * - bearerAuth: [] * responses: * 200: * description: Successful response * content: * application/json: * schema: * type: object * properties: * message: * type: string * 401: * description: Unauthorized * 500: * description: Server error */ export const getStatus: GetStatus async (req, res) { return res.json({ message: OK }); };注意注释里的路径/status要与main.wasp.ts中api声明的路径对应。GetStatus这类类型是 Wasp 编译器根据api声明生成的TypeScript 项目需要先在 wasp 文件中声明 API 并让wasp start保持运行类型才会生成见 API 文档中的说明。对不同类型的请求指南给出了对应的注释写法可按需套用POST 请求带 body 时在注释中声明requestBody含 schema 和required字段/** * swagger * /users: * post: * summary: Create a new user * tags: * - Users * requestBody: * required: true * content: * application/json: * schema: * type: object * required: * - email * - password * properties: * email: * type: string * format: email * password: * type: string * minLength: 8 * responses: * 201: * description: User created successfully * 400: * description: Invalid input */路径参数通过parameters中in: path的条目描述/users/{id}查询参数用in: query条目描述写法见 Swagger UI 指南的 Documenting Different Request Types 一节。6. 启动应用并验证文档页用wasp start启动应用默认客户端在 3000 端口、服务器在 3001 端口端口被占用时 Wasp 会自动选择下一个可用端口并在启动时打印实际 URLwasp start然后浏览器访问http://localhost:3001/api-docs应看到 Swagger UI 页面顶部 server 地址为WASP_SERVER_URL的值。验证方式页面中列出了你在 JSDoc 注释里声明的端点按tags分组展开某个端点点击 Try it / 发送请求按钮由explorer: true开启填写参数后请求会发往页面顶部的 server 地址对带bearerAuth的端点先在页面上填写Bearer tokenpersistAuthorization: true会让该信息在会话中保留再发送请求验证 200 与 401 的表现是否符合注释中声明的响应。可选自定义文档页外观与分组指南还提供两类定制项都属于可选分支不影响主流程通过swaggerUi.setup的第二个参数调整样式和站点信息swaggerUi.setup(swaggerDoc, { customCss: .swagger-ui .topbar { display: none } .swagger-ui .info { margin: 20px 0 } , customSiteTitle: My API Documentation, customfavIcon: /favicon.ico, });在scripts/generate-swagger.js的definition中加入tags数组可以为分组提供描述const spec swaggerJsdoc({ definition: { // ... other config tags: [ { name: Users, description: User management endpoints }, { name: Posts, description: Blog post endpoints }, { name: Auth, description: Authentication endpoints }, ], }, apis: [./src/**/*.ts, !./src/swaggerSpec.ts], });更多配置选项参考指南末尾给出的 swagger-jsdoc 与 swagger-ui-express 上游文档。限制与维护点spec 是离线生成的swaggerSpec.ts只有在运行node scripts/generate-swagger.js后才会更新新增或修改了 JSDoc 注释但没有重新生成文档页不会反映变化。生成文件的处理src/swaggerSpec.ts建议加入.gitignore生产环境依赖打包进服务器的该文件而不是运行时扫描src/。helmet 调整的边界关闭contentSecurityPolicy和hsts仅通过/api-docs命名空间的middlewareConfigFn生效不要把这些配置放进全局server.middlewareConfigFn否则会作用于所有请求。路径一致性apiNamespace的路径、swaggerOptions.url和访问地址三者必须一致本例统一为/api-docs否则文档页拉不到 spec。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Wasp 如何为自定义 API 添加 Swagger UI 文档页并在线测试端点

相关推荐

2026 AI应用与智能体开发：Java+Python双栈实战课程全拆解

数据共享与交换实战：从接口设计到平台化部署

技术人如何用RAG项目展现真实工程能力

更多资讯

用Python手写BP神经网络实现鸢尾花分类：从原理到调参

基于GPT-6 Astra的跨平台GitHub查询机器人：QQ与飞书双端实现

Python毕业设计：恶意代码检测分类平台搭建与实现

二分查找算法原理、实现与优化指南

Doris+Lance实现毫秒级跨模态联合检索

移动应用安全测试全流程指南与最佳实践

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？