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

В соответствии с сайтом Swagger существует два подхода: снизу вверх и сверху вниз.

У меня есть существующий сервер NodeJS, который я хотел бы развернуть в среде Azure, для которой требуется документ swagger (API APP).

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

Ответ 1

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

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

Добавьте зависимости в наш package.json и запустите npm install, чтобы установить их. Зависимости должны быть:
```
"dependencies": {
        "swagger-node-express": "~2.0",
        "minimist": "*",
        "body-parser": "1.9.x",
        ...
}
```
Загрузите zip-проект Swagger-UI, скопируйте папку dist в корневую директорию нашего проекта, каталог должен почти нравиться:

Ввести значения в начале app.js:

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

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

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

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

Задайте информацию для API:

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

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

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

Завершите конфигурацию swagger:

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');

Настроить зависимость файла документа в /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";
}

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

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

Вот мой test sample repo для вашей справки.

Ответ 2

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

Используя swagger-node-express, который, по моему мнению, очень громоздкий.
С помощью редактор swagger вручную создайте документ для swagger, как это предлагается в SO Ответ

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

Ответ 3

Вопрос немного старый, но все же. Можно полностью генерировать спецификацию Swagger (OpenAPI), просто встраивая аналитическое промежуточное ПО следующим образом: https://github.com/mpashkovskiy/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