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)

Typedoc will show any JSDoc tags you add but there's no special handling for API doc tags. TypeDoc is more focused on documenting internal code. — Chic, Nov 30 '20 at 23:13

score 2 · Answer 1 · edited Dec 29 '20 at 13:44

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

score 2 · Answer 2 · answered Mar 10 '22 at 13:58

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)

How to Generate REST API documentation with Typescript and Node?

2 Answers2