## Установка
npm install swagger-autogen-docДля установки данного модуля используйте
``
npm install swagger-autogen-doc
Подключение к проекту происходит путём импорта модуля и передачи в него объекта созданного через функцию express() и путь к директории проекта.
Пример подключения:
`javascript
const express = require('express')
const app = express()
/*
Подключение API к app
*/
const options = {};
require("swagger-autogen-doc").configure(app, options, __dirname);
`
_ВАЖНО!_ Вызов функции .confugure() использовать после подключения API к объекту app. Т.к. не все данные могут быть получены.
Модуль расчитан на шаблон разработки, где каждый API лежит в отдельном файле и структуру файла подобной этой:
`javascript
const { swaggerApi } = require("swagger-autogen-doc");
const Joi = require('joi')
module.exports = () => {
return swaggerApi({
method: 'get',
path: '/api/v1/public/test',
validationSchema: Joi.object({
email: Joi.string().email()
}),
handler: async function (req, _res) {
return res.status(200).json({message: "Hello world"});
}
});
}
`
Функция swaggerApi(object) используется получение информации о данном объекте. Поэтому и рекомендуется использовать configure() после подключения API для отработки данных функций.
Описание Joi схемы следующее, если при её описании были использованы example(), то это будет использоваться для вывода примера запроса в документации.
_ВАЖНО!_. Примеры для query параметров не будут отображаться в документации, но будут использованы для тестовых запросов
Синтаксис комментариев для описания имеет струкутуру похожую на HTML и XML. Для обозначения, что это именно комментарий для swagger генератора, используются тег \
Список доступных тегов:
* summary - тег для описания заголовка API. Например:
`
Авторизация пользователя
* remarks - тег для описания API
`
Принимает в теле запроса логин и пароль
* param - тег для описания параметров query API. Имеет атрибуты:
1. required - обязательный ли параметр
2. name - имя параметра
`
Имя пользователя
* body - тег для описания тела запроса API. Имеет атрибуты:
1. required - обязательный ли параметр
2. name - имя параметра
`
Данные о пользователе
* response - тег для описания возможных ответов API. Имеет атрибуты:
1. code - код ответа
`
Запрос успешен
Пример описания кода:
`javascript
/*
Тестовый API
Тестовый API, ничего не принимает и всегда возвращает ответ с кодом 200 и текстом "Hello World"
*/
const { swaggerApi } = require("swagger-autogen-doc");
const Joi = require('joi')
module.exports = () => {
return swaggerApi({
method: 'get',
path: '/api/v1/public/test',
validationSchema: Joi.object({
email: Joi.string().email()
}),
handler: async function (req, _res) {
return res.status(200).json({message: "Hello world"});
}
});
}
`
Также в комментариях имеется возможность использовать стандартные теги HTML, например, \
Объект настроек принимает в себя следующие поля:
* folderApi - путь к папке где лежат API. Для оптимизации парсинга проекта
* pathDoc - путь куда будет сохраняться .json файл документа относительно директории проекта. По-умолчанию равен "./swagger.json"
* endpointSwagger - endpoint для доступа к документации. По-умолчанию равен "/api-docs"
* url - объект настройки путей API который будет использоваться в разработке. Имеет свойства:
* templateRout - шаблон endpoint. По-умолчанию равен "/api/:version/:controller/:resources+". То есть каждый endpoint будет иметь такую схему, например: '/api/v1/public/login'.
Здесь v1 - version, public - controller, login - resources.
* groupBy - по какому из частей endpoint будет группировка. По-умолчанию "controller".
* Title - название документации
* Version - версию документации
* Schemes - массив схем для запросов, по-умолчанию хранит в себе все схемы. Может включать в себя:
* http
* https
Пример подключения авторизации:
`javascript
const { AuthTypes } = require("swagger-autogen-doc");
const apiKey = new AuthTypes.ApiKeyAuth();
apiKey.Name = "Authorization";
const options = {
auth: {
Auth: apiKey
}
}
require("swagger-autogen-doc").configure(app, options, __dirname);
`
В объекте AuthTypes лежат прототипы методов авторизации, такие как:
* ApiKey - имеет свойство Name, которое будет передаваться в заголовок запроса
* Bearer
* Basic
После настройки выбранного объекта, необходимо подключить объект к объекту Swagger. Для этого при создании объекта OptionsSwagger передаем объект с полем auth. При добавлении объекта в это поле, имя поле будет названием схемы к которой можно будет подключать API.
Например:
`javascript
const { swaggerApi } = require("swagger-autogen-doc");
const Joi = require('joi')
module.exports = () => {
return swaggerApi({
method: 'get',
path: '/api/v1/public/test',
validationSchema: Joi.object({
email: Joi.string().email()
}),
handler: async function (req, _res) {
return res.status(200).json({message: "Hello world"});
}
}, "Auth");
`
Здесь функция swaggerApi принимает вторым аргументов имя схемы, которая будет использоваться для данного API.
При первом запуске модуль попытается произвести запросы по всем АПИ для получения схемы ответов. Для этого требуется вызвать событие 'run' в app и передать в него порт. Например:
`javascript`
port = process.env.PORT || 3000;
app.emit('run', port);
_ВАЖНО!_. Событие надо вызвать после запуска сервера, иначе схемы не будут получены.
После тестовых запросов в документацию будут добавлены схемы ответов соответствующих запросов.
Тестовые данные для запросов генерируются автоматически, если не были указаны примеры в схемах черезе example(). Например:
`javascript``
Joi.object({
email: Joi.string().email().example("test@mail.com");
})
=======
В данном генератора используются joi схемы для примеров параметров запроса.