How to Generate REST API documentation with Typescript and Node?

Question

Can I use https://github.com/TypeStrong/typedoc to create REST API docs like https://apidocjs.com/?

Any suggestions on how to reuse TypeScript types to generate REST API docs are welcome (Using Next.js)

Answer 1

Have you checked the npm package apidoc?

It generates API documentation based on code comments:

/**
 * @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.
 */

And there are companion tools / converters for Gulp, Grunt, Eclipse, Sublime Text, Docmaster, Markdown, Swagger... (cf. apidoc GitHub README.md)

Answer 2

If what you actually want is to describe your API in TypeScript and have a Swagger/OpenAPI definition come out of it, try https://github.com/airtasker/spot

IT will not only generate REST API documentation, it will also let you run a mock server with random data that fits the REST API definition (for testing clients) and a data model validator (for testing servers).

Example from the project 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;
}