Использование типов TypeScript вместо Swagger

[Shatun]

Сваггер-это общий формат, понятный всем, а не только js/ts программистам.

Мне интересно в вашем решении как пишутся например мобильные приложения? Или интеграции с другими АПИ, не на js? Сторонние команды?

Как вы выставялете наружу документацию?

[marvin_42]

Согласен насчёт свагера, кроме того, это еще и интерактивный доступ к этой документации, где можно ручками потыкать и поотправлять запросы. Очень удобно, особенно в комбинации с ASP.Net.

Но использование сваггера с js/ts сулит проблемами. По сравнению, например, с тем же ASP.Net, подключить Swagger к ExpressJs так себе задачка. Кроме того, существующие решения в основной своей массе требуют определённой структуры написания кода. Часть этих решений вообще опираются на JSDoc, что по моему мнению, очень плохо. Потому что: метод изменил, а комментарий исправить забыл - и ну просто никак компиляторы и рабочие утилиты тебе этого не подскажут, не намекнут. Это всё приводит к тому, что на платформе nodejs Swagger не так распространён. В описанном способе, можно писать код в каком угодно стиле/подходе - в данном случае все подходы равны. Есть, конечно, ровнее, но о нём будет рассказано в следующей публикации.

Касательно первого вопроса: создаём проект контрактов/интерфейсов (в данной статье это shared) - и подключаем эту shared библиотеку к проектам, откуда планируется дергать соответствующее апи. Если проект на js/ts (React.Native) - то всё просто. Но если решение на другом языке, такой способ уже не прокатит. Но в самом начале статьи я как раз обозначил условие, при котором в swagger отпадает необходимость.

В моей практике были ситуации, когда нужно было пилить/интегрировать службы не на js. Это были внутренние проекты, и с моей стороны было достаточно передать доступ к репозиторию shared с интерфейсами RestAPI, которые на самом деле выглядят почти как json, но где вместо значений указан тип ключа, и url ендпоинта. У людей с C#/Java/PHP, кто знаком с форматом json не возникало вопросов :)

Для внешних интеграций тоже всё очень просто, можно два способа:

1. Поднимается простой сервак (можно даже отделаться одним nginx), который отдаёт по названию службы соотсветсвующий файлик ts из папки shared монорепозитория. Обновился интерфейс, стянули с гита изменения, и всё снова актуально. Открываешь страницу http://site.site/shared/task.ts - и перед тобой полное описание RestApi. В моём примере не показано, но вообще я обычно пишу комменты к методам, чтобы прям совсем было всё очевидно.

2. Реализуется в сервере endpoint, который будет возвращать свой файлик с интерфейсами. Это выглядит так:

const getAPI = EndpointMeta<
  {
    params?: {
      controller?: `${string}.ts`;
  	};
  },
  Promise<string>
> = {
  _: "endpointMeta",
  url: "/:controller",
  route: "/docs",
  method: "get",
};

Но вопрос о целесообразности применения такого подохода зависит от существующих проектов и команды, если вы пишите новый сервер на ExpressJS, который будете интегрировать с другими, написанных на других языках, то тогда навряд ли есть смысл во всём этом. Хотя повторю, существующее решение не связывает по рукам и ногам того, кто пишет сервак.