swagger - Hvordan genererer man REST API-dokumentation med Typescript og Node?

Kan jeg bruge https://github.com/TypeStrong/typedoc til at oprette REST API-dokumentation som https://apidocjs.com/?

Alle forslag til, hvordan man kan genbruge TypeScript-typer til at generere REST API-dokumentation, er velkomne (Bruger Next.js)

Svar #1

Hvis det, du faktisk ønsker, er at beskrive dit API i TypeScript og få en Swagger/OpenAPI-definition ud af det, så prøv https://github.com/airtasker/spot

IT vil ikke kun generere REST API-dokumentation, det vil også lade dig køre en mock-server med tilfældige data, der passer til REST API-definitionen (til test af klienter) og en datamodelvalidator (til test af servere).

Eksempel fra projektets 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;
}

Svar #2

Har du tjekket npm-pakken apidoc?

Det genererer API-dokumentation baseret på kodekommentarer:

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

Og der findes ledsagende værktøjer/konvertere til Gulp, Grunt, Eclipse, Sublime Text, Docmaster, Markdown, Swagger... (jf. apidoc GitHub README.md)

Relaterede artikler