Самодокументируемый REST сервер (Node.JS, TypeScript, Koa, Joi, Swagger)

[apapacy]

Такого функционала очень нехватает и к сожалению почему-то нет проектов с мощной поддержкой. Пожалуй кроме nestjs (см. docs.nestjs.com/recipes/swagger)

[DragFAQ]

Почитал. Весьма прикольная штука. На досуге подумаю как к ней валидатор прикрутить.
Спасибо.

[dos]

Там уже есть валидатор docs.nestjs.com/techniques/validation но мы у себя используем такой подход:

@AjvValidation({
  properties: {
    email: { type: 'string' },
    password: { type: 'string' },
  },
  required: ['email', 'password'],
})
@Post()
create(@Body() createUserDto: CreateUserDto) {
  return 'This action adds a new user';
}

также вместо AjvValidation есть JoiValidation если кто-то ещё предпочитает Joi, а не Ajv.

[DragFAQ]

Да вот некрасиво так. Получается надо описывать Юзера два раза. Я наоборот хочу от этого уйти.

[dos]

К сожалению типы TS не настолько выразительны, чтобы полностью реализовывать возможности Ajv валидатора, поэтому мы и не стали пытаться их как-то совмещать.

[backenda]

Зачем вообще тратить время на CRUD-подобный REST если есть GraphQL, который превосходит REST почти во всем?

[DragFAQ]

Кстати, да! Как раз сейчас внедряем его. Очень крутая штука. Но в данной статье CRUD я описал просто в качестве примера. Да и статья не о преимуществах и недостатках REST )

[Alexufo]

кроме неясности что проще поддерживать?

[apapacy]

Я тоже пытаюсь у себя на работе агитировать за graphql пока с нулевым результатом. То что restapi сейчас превалирует приивсехтего недостатках это уже его плюс. Т. к. есть масса готовых средств и готовых разработчиков на restapi. В то же время и у graphql есть несколько задач которые как бы и не входят в сам стандарт но которые нужно решать. Они многократно обсуждались перечислю их ещё раз
1 разделение ролей и пользователей
2 обработка ошибок
3 проблема select n + 1 при запросах с глубоким уровнем вложенности

[dos]

Частично ваши задачи решаются так:
1. RLS в PostgreSQL, если вы её используете.
2. К сожалению не понятно в чем проблема обработки ошибок.
3. «Пост» обработка graphql запроса с целью разбора и последующей агрегации select n + 1 запросов в join'ы.

[apapacy]

1. Почему Постгрес? Возможно в резольверах юзать например микросервисы или запросы к разным базам данных. И кроме этого переносить роли и пользователей на уровень базы данных это уже как бы шаг назад.
2. Эта тема достаточно широко обсуждаема. Не я ее открыл. Graphql имеет встроенный механизм обработки ошибок который немного напоминает неотловленный throw Error. В частности при невалидных входных данных. А хотелось бы иметь более кастомизируемый контроль. Например отдать JSON в котором будут перечислены невалидные поля и локализованные сообщения об ошибках чтобы это отработать на фронтенде в готовом виде.
3. Эта проблема была рассмотрена в относительно недавнем посте на Хабре habr.com/ru/post/412847 Решения конечно есть и даже прямо от фейсбука. Но вместе с тем надо признать что эта проблема наверное самая сложная т.к. относится к архитектуре построенной на резольверах.

[teemour]

Внимательно не читал, как вы работаете над именно разработкой API — ревью там, пул реквесты. Или как имплементировали так и задокументировали? Версионирование?

[Pilat]

Со swagger я как-то столкнулся с проблемой. OpenAPI v2 — это первая нормально реализованная в swagger, для неё был инструментарий в Eclipsе. При появлении OpenAPI версии 3 инструментарий быстро перешёл на неё и теперь версия 2 поддерживается никак. Наверняка эта история повторится, так что swagger — это проект, который будет работать лет пять, потом резко станет неподдерживаемым.