如何使用 Typescript 和 Node 生成 REST API 文档？答案

【问题标题】：How to Generate REST API documentation with Typescript and Node?如何使用 Typescript 和 Node 生成 REST API 文档？
【发布时间】：2022-03-10 21:58:43
【问题描述】：

我可以使用https://github.com/TypeStrong/typedoc 创建像https://apidocjs.com/ 这样的REST API 文档吗？

欢迎任何关于如何重用 TypeScript 类型来生成 REST API 文档的建议（使用 Next.js）

【问题讨论】：

Typedoc 将显示您添加的任何 JSDoc 标签，但对 API doc 标签没有特殊处理。 TypeDoc 更侧重于记录内部代码。

标签： typescript swagger next.js api-doc typedoc

【解决方案1】：

如果您真正想要的是在 TypeScript 中描述您的 API 并从中得出 Swagger/OpenAPI 定义，请尝试 https://github.com/airtasker/spot

IT 不仅会生成 REST API 文档，还会让您运行一个模拟服务器，其中包含符合 REST API 定义（用于测试客户端）的随机数据和一个数据模型验证器（用于测试服务器）。

项目自述文件中的示例：

import { api, endpoint, request, response, body } from "@airtasker/spot";

@api({
  name: "My API"
})
class Api {}

@endpoint({
  method: "POST",
  path: "/users"
})
class CreateUser {
  @request
  request(@body body: CreateUserRequest) {}

  @response({ status: 201 })
  response(@body body: CreateUserResponse) {}
}

interface CreateUserRequest {
  firstName: string;
  lastName: string;
}

interface CreateUserResponse {
  firstName: string;
  lastName: string;
  role: string;
}

【讨论】：

【解决方案2】：

你检查过npm包apidoc吗？

它根据代码cmets生成API文档：

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id User's unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

还有用于 Gulp、Grunt、Eclipse、Sublime Text、Docmaster、Markdown、Swagger 的配套工具/转换器...（cf.apidoc GitHub README.md）

【讨论】：