Генерируйте документы на swagger / openapi из набора тестов Mocha / Chai

Question

Я хочу использовать Swagger / OpenAPI для стандартизации документации. Большинство API построено на NodeJS, и я провожу интеграционное тестирование с Mocha & Chai, которое очень помогает быстро убедиться, что API не сломан после внесения изменений. Насколько я понимаю, использование Swagger не заменит мой интеграционный тест, но позволит разработчикам легко узнать, как использовать мой API. Если я смогу связать свои усилия по документированию с моим набором тестов, это упростит текущее сопровождение документации. Когда я добавляю или изменяю тест, я могу обновить документы API там же.

Я думал о том, чтобы использовать YUIDoc или JSDoc , который генерирует документацию API из комментариев в источнике. Но ни тот, ни другой не соответствуют спецификации OpenAPI. Затем я нашел Swagger-JSdoc и решил, что могу просто поместить все комментарии в код моего набора тестов, поскольку я уже там указываю, что тестировать в конечных точках.

Есть ли другой способ / рабочий процесс, который мог бы быть более эффективным для новых или существующих проектов? Как я могу приблизить свои усилия по документированию к моему тестовому набору, чтобы улучшить текущее сопровождение документации?

Answer 1

Я только что опубликовал модуль npm для того же самого. Не уверен, что вы нашли альтернативу, если нет, пожалуйста, не стесняйтесь попробовать. https://github.com/LmntrX/mocha-swagger/

Установить Мокко-чванство глобально с

npm install -g mocha-swagger

Затем выполните следующую команду:

mocha-swagger path/to/project/tests

Эта команда рекурсивно проанализирует тестовые файлы в вашем тестовом каталоге и сгенерирует базовый swagger.json файл в текущем каталоге.

Примечание: обратите внимание, что сгенерированная спецификация будет содержать только ваши маршруты, методы и параметры пути.