Предоставление документации с API-интерфейсом Node/JS REST

Question

Я ищу, чтобы создать REST API с помощью Node и Express, и я хотел бы предоставить ему документацию. Я не хочу делать это вручную, и кажется, что есть решения, доступные в формах Swagger, RAML и Api Blueprint/Apiary.

Я бы хотел, чтобы документация автоматически генерировалась из кода API, как это возможно в среде .NET с помощью Swashbuckle или Microsoft, но они стали возможными благодаря сильной типизации и отражению.

Для JS-мира кажется правильным вариантом использовать разметку Swagger/RAML/Api Blueprint для определения API, а затем сгенерировать документацию и вывести сервер из этого. Первое кажется простым, но я менее уверен в этом. То, что я видел в генерации кода сервера для всех этих параметров, кажется очень ограниченным. Должен быть какой-то способ отделить автоматически сгенерированный код от ручного кода, чтобы можно было легко обновить определение, и я не видел никаких признаков или дискуссий. Это не похоже на непреодолимую проблему (я больше знаком с .NET, чем с JS, поэтому я легко мог чего-то упустить), и упоминается об этой проблеме и решениях, которые обрабатываются в previous Stack Overflow question более года назад.

Может ли кто-нибудь сказать мне, если я пропущу/не понял что-либо и если какое-либо решение для вышеуказанной проблемы существует?

Answer 1

Мой опыт работы с API и динамическими языками заключается в том, что акцент делается на проверке вместо генерации кода.

Например, если использовать скомпилированный язык, я генерирую артефакты из спецификации API и использую это для обеспечения правильности. Круглое отключение поддерживается через создание интерфейсов вместо конкретных классов.

С динамическим языком спецификация используется во время тестирования, чтобы гарантировать, что и весь определенный API будет покрыт испытанием, и что ответы соответствуют спецификации (я склонен не проверять запросы из-за закона Postel, но это возможен тоже).

Answer 2

начальная версия swagger-node-express сделала именно это - вы бы определили некоторые метаданные из маршрутов, моделей и т. Д., И документация автоматически сгенерировалась бы из нее. Учитывая динамический javascript, это стало немного громоздким для многих, поскольку для этого требуется, чтобы метаданные обновлялись по сравнению с моделями несколько развязанным образом.

Ускоренный передовой и последний проект swagger-node использует альтернативный подход, который можно рассматривать как «генерирующий документ из кода» в некотором смысле. В этом проекте (и swagger-inflector для java и connexion для python) подходите к тому, что спецификация swagger равна DSL для api, а логика маршрутизации обрабатывается тем, что определено в документе swagger. Оттуда вы просто реализуете контроллеры.

Если вы рассматриваете спецификацию swagger как «код», то это очень эффективный способ - документация может буквально никогда не устаревать, поскольку она используется для построения всех маршрутов, проверки всех входных переменных и подключите API к бизнес-уровню.

Хотя верно генерации кода, например, что доступно из проекта swagger-codegen может быть весьма эффективным, это требует некоторой умной интеграции с вашим кодом после вы изначально построить сервер. Это соображение полностью исключено из рабочего процесса тремя вышеупомянутыми проектами.

Надеюсь, это полезно!