Создайте документ Swagger для существующего сервера NodeJS

Несложно интегрировать Swagger в существующие экспресс-приложения, следуя этому руководству. .

Как правило, мы можем выполнить следующие шаги:

1. Добавьте зависимости в наш package.json и запустите npm install, чтобы установить их. Зависимости должны быть:

   "dependencies": {
           "swagger-node-express": "~2.0",
           "minimist": "*",
           "body-parser": "1.9.x",
           ...
   }
   

2. Загрузите zip-проект Swagger-UI, скопируйте папку dist в корневой каталог нашего проект, каталог должен выглядеть примерно так:

3. Введите зависимости в начале app.js:

   var argv = require('minimist')(process.argv.slice(2));
   var swagger = require("swagger-node-express");
   var bodyParser = require( 'body-parser' );
   

4. Настройте подпуть для документа swagger:

   var subpath = express();
   app.use(bodyParser());
   app.use("/v1", subpath);
   swagger.setAppHandler(subpath);
   

5. Убедитесь, что /dist может обслуживать статические файлы в режиме экспресс: app.use(express.static('dist'));

6. Установите информацию для API:

   swagger.setApiInfo({
       title: "example API",
       description: "API to do something, manage something...",
       termsOfServiceUrl: "",
       contact: "[email protected]",
       license: "",
       licenseUrl: ""
   });
   

7. Введите /dist/index.html для пользовательского интерфейса swagger:

   subpath.get('/', function (req, res) {
       res.sendfile(__dirname + '/dist/index.html');
   });
   

8. Завершите конфигурации чванства:

   swagger.configureSwaggerPaths('', 'api-docs', '');
   
   var domain = 'localhost';
   if(argv.domain !== undefined)
       domain = argv.domain;
   else
       console.log('No --domain=xxx specified, taking default hostname "localhost".');
   var applicationUrl = 'http://' + domain;
   swagger.configure(applicationUrl, '1.0.0');
   

9. Настройте зависимость файла документа в /dist/index.html:

   if (url && url.length > 1) {
       url = decodeURIComponent(url[1]);
   } else {
       <del>url = "http://petstore.swagger.io/v2/swagger.json";</del>
       url = "/api-docs.json";
   }
   

10. Создайте файл api-docs.json с информацией о ваших API, поместите его в папку dist.

Запустите приложение Express локально, посетите http://localhost:3000/v1, мы можем проверить документ swagger.

Вот мой репозиторий тестовых образцов для справки.

Вопрос немного староват, но все же. Можно полностью автоматически сгенерировать спецификацию Swagger (OpenAPI), просто внедрив промежуточное программное обеспечение для анализа, например: https://github.com/mpashkovsky/express-oas-generator

const express = require('express');    
const expressOasGenerator = require('express-oas-generator');
let app = express();
expressOasGenerator.init(app, {});

запустите некоторые тесты клиента или REST API для вашей службы и откройте http://host:port/api-docs

Многие разработчики до сих пор сталкиваются с этой проблемой, поэтому я создал инструмент с открытым исходным кодом, чтобы помочь — этот инструмент чем-то похож на Git для API. Он работает, запуская прокси-сервер, пока вы разрабатываете API, анализируете трафик и обновляете спецификацию для вас по мере изменения поведения API. Надеюсь, рабочий процесс сэкономит вам много времени: https://github.com/opticdev/optic

Насколько мне известно, ваши варианты:

1. Использование swagger-node-express, что, на мой взгляд, очень громоздко.
2. Написание документа swagger вручную с помощью редактора swagger, как предлагается в этом ТАК ответ

Если вы выберете вариант 2, вы можете использовать swagger-ui-express для сгенерировать swagger-ui

Для большинства альтернатив требуется какая-то спецификация API через Json, Yaml или даже встроенная в JSdocs. С другой стороны, есть некоторые анализаторы времени выполнения, перехватывающие HTTP-запросы и создающие эту спецификацию по требованию.

express-sitemap-html использует другой подход к проверке экспресс-объекта и его маршрутов. во время настройки. Таким образом, он всегда предоставляет актуальный пользовательский интерфейс swagger для установленных маршрутов в существующем экспресс-экземпляре.

const sitemap = require('express-sitemap-html')
...
sitemap.swagger('Title', app) // app is an express instance

Затем получите пользовательский интерфейс swagger из вашего домена /api-docs.