Как я уже писал ранее, мне нравится эта модель для документирования API непосредственно в исходном коде, где реализованы API. Это помогает разработчикам помнить о необходимости синхронизации реализации и документации API-интерфейсов, а также повышает осведомленность о совместимости API-интерфейсов. Вы можете использовать этот подход не только для приложений Java, но и для приложений Node.js, использующих популярную среду веб-приложений Express , например, через модуль npm swagger-node-express . Проверьте метод «findById» в примере.
Однако я не уверен насчет статуса этого модуля. Он ссылается на проект GitHub github.com/swagger-api/swagger-node-express, который, похоже, больше не существует. Вместо этого он перенаправляет на другой библиотечный swagger-узел, который кажется преемником или заменой. Хотя библиотека swagger-node поставляется с множеством дополнительных приятных возможностей, я еще не выяснил, как документировать API непосредственно в исходном коде. Модуль swagger-node использует отдельные файлы yaml для определения API. В этой модели документация по API близка к реализации API, но не напрямую в тех же файлах. Поскольку модуль узла-сваггера связан с сайтом Swagger и поскольку код находится в API-интерфейсе Swagger Организация GitHub, ниже я опишу, как использовать этот модуль в приложениях Node.js.
Библиотека swagger-node поставляется с хорошим редактором для определения API и интегрированным веб-приложением для тестирования API. Следуя первому процессу разработки API, вы можете использовать фиктивный режим для «тестирования» API без фактической реализации API / контроллеров. С помощью команды проверки вы можете проверить правильность определений API и структур проекта. Существует мастер для создания проектов для различных структур API, таких как Express, Connect и другие, которые создают базовую структуру и конфигурацию для новых проектов.
Существует простая инструкция из пяти шагов, чтобы создать свой первый пример hello world. Я не буду повторять шаги здесь. Только одна вещь, которая смутила меня. Пример определяет, что он возвращает JSON, но на самом деле он возвращает только тип контента JSON со строкой. Поэтому я изменил одну строку в файле controllers / hello_world.js.
function hello(req, res) {
// variables defined in the Swagger document can be referenced using req.swagger.params.{parameter_name}
var name = req.swagger.params.name.value || 'stranger';
var hello = util.format('Hello, %s!', name);
// this sends back a JSON response which is a single string
//res.json(hello);
res.json({ message: hello});
}
Чтобы запустить проект Swagger, вам нужно вызвать команду «swagger project start» или «node app.js», если вы хотите запустить только основное приложение Node. После этого вы можете запустить API и получить определение API Swagger.
http://127.0.0.1:10010/hello?name=Scott
http://127.0.0.1:10010/swagger
Чтобы запустить редактор, вызовите команду «swagger project edit».
http://127.0.0.1:51351/#/
http://127.0.0.1:51351/editor/spec
Вот скриншот редактора с примером Hello World.