Блог

Главная - Вопросы по программированию - Как сгенерировать документацию REST API с помощью Typescript и Node?

Как сгенерировать документацию REST API с помощью Typescript и Node?

#typescript #swagger #next.js #api-doc #typedoc

#typescript #swagger #next.js #api-документ #typedoc

Вопрос:

Могу ли я использовать https://github.com/TypeStrong/typedoc для создания документов REST API, таких как https://apidocjs.com /?

Любые предложения о том, как повторно использовать типы TypeScript для создания документов REST API, приветствуются (с использованием Next.js )

Комментарии:

1. Typedoc покажет любые теги JSDoc, которые вы добавляете, но для тегов API doc нет специальной обработки. TypeDoc больше ориентирован на документирование внутреннего кода.

Ответ №1:

Вы проверили apidoc пакета npm?

Он генерирует документацию 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 )

Ответ №2:

Если вы действительно хотите описать свой API в TypeScript и получить из него определение 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;
}
Метки: