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

Question

我能否使用https://github.com/TypeStrong/typedoc生成类似于https://apidocjs.com/的REST API文档？

欢迎提供任何在使用Next.js时重用TypeScript类型以生成REST API文档的建议。

- Srdjan Stajic

---

Typedoc会显示您添加的任何JSDoc标签，但没有特殊处理API文档标签。TypeDoc更专注于记录内部代码。 - Chic

Answer 1

你是否查看过npm包apidoc？

它可以根据代码注释生成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等相关的辅助工具/转换器...(参见apidoc GitHub README.md)

- Lucas Cimon

Answer 2

如果你想用TypeScript描述你的API并生成Swagger/OpenAPI定义，可以尝试使用https://github.com/airtasker/spot。它不仅可以生成REST API文档，还可以让你运行一个模拟服务器，使用符合REST API定义的随机数据（用于测试客户端），以及数据模型验证器（用于测试服务器）。

以下是项目README中的示例：

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;
}

- Renato