Установка и настройка Swagger Validator

Kate · 25 Окт 2021

Что? Зачем?

Swagger - популярное решение для документирования API. Он использует OpenAPI Specification. У этого инструмента есть несколько вариантов ведения документации: .json или .yml файлы. Мы документируем всё в .json файлах. Писать документацию это отлично и прекрасно, но было бы замечательно если она будет валидной и рабочей.

Что такое валидатор и как он работает?

Для того, чтобы наша документация была валидной у Swagger есть валидатор. Да, json схему OpenAPI спецификации можно провалидировать спокойно онлайн на нескольких ресурсах (тыц, тыц, тыц), но гораздо удобнее, когда такой инструмент есть здесь и рядом. В документации Swagger в правом нижнем углу есть значок-изображение, который сигнализирует о валидности схемы, которая была разработана.

По-умолчанию, валидация происходит благодаря онлайн валидатору. Он обращается по урлу к нашей документации, валидирует и сообщает ответ в виде изображения. При клике по этому изображению происходит переход на страницу валидатора с дебаг информацией, где отображаются ошибки или сообщение “всё ок”.

Почему не работает онлайн валидатор

В принципе, онлайн валидатора вполне достаточно, если ваша документация открыта в публичном доступе. А если документация в закрытом от внешних глаз доступе онлайн валидатор не поможет. Что же делать и как же быть? Оказывается - всё очень просто. Особенно просто писать о том, что просто, когда всё уже установлено и настроено. Есть пакет на github, который можно установить с помощью докера и всё будет прекрасно.

Попытка установить пакет без использования докера

А что делать если проект не упакован в докер? И тут начинаются танцы с бубном. Сами танцы я пропущу и перейду сразу к бубнам. Для запуска валидатора необходимо установить Apache Maven и java. И, конечно же, выкачать сам пакет:

git clone https://github.com/swagger-api/validator-badge git
cd git
mvn package jetty:run
Последняя команда запускает maven с валидатором на борту. На этом всё - валидатор доступен по ссылке http://localhost:8080/validator?url=<json_schema_url>. В качестве параметра url необходимо передать путь к .json документации. Например, в нашем случае это выглядит вот так http://localhost:8080/validator?url=https://domain.local/swagger/resources/openapi.json

Работает, работает да не работает

Валидатор и вправду работает, если у вас один .json файл без использования $refв схеме. Необходимо обладать сумасшедшим запасом терпения, если у вас большое (5+) количество эндпойнтов с разными response объектами, чтобы хранить их в одном .json файле.

У нас в команде основной файл содержит ссылки на другие подсхемы и при таком подходе валидатор всегда говорит о том, что всё ок - всё валидно даже если в подсхемах есть очевидные ошибки. Вариант решения этой проблемы на поверхности - нужен цельный файл без ссылок на подсхемы.

Генерирование общего файла без $ref

С этим нам помог инструмент swagger-merger. Здесь всё просто: устанавливаете пакет и выполняете команду

./node_modules/swagger-merger/bin/swagger-merger.js -i public/swagger/resources/openapi.json -o public/swagger/resources/combinedSchema.json
Мы для удобства добавили скрипт в composer.json

"scripts": {
"swagger-merger": [
"./node_modules/swagger-merger/bin/swagger-merger.js -i public/swagger/resources/openapi.json -o public/swagger/resources/combinedSchema.json"
]
},
"scripts-descriptions": {
"swagger-merger": "Merge openapi references to one combined schema."
},
и всё сводится к трём словам в командной строке composer swagger-merger. После создания файла указываем ссылку на него валидатору и теперь валидатор корректно валидирует нашу схему.

Отображение статуса валидации

Подход, который я описал выше удобен для локальной разработки когда есть возможность обратиться к валидатору, передав ему ссылку на документацию. Но ведь гораздо удобнее чтобы результат работы валидатора отображался сразу в схеме. И тут ещё немного работы осталось.

Нам необходимо в скрипте инициализации Swagger на странице документации указать URL валидатора:

<script>
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
...
validatorUrl: "http://api_doc_url/swagger/badge"
});
// End Swagger UI call region
window.ui = ui;
};
</script>
Решили указать не тот URL, на котором запущен сам валидатор, а наш кастомный. Для обработки запроса к нему есть 2 пути: через nginx и обычными средствами php.

Валидатор нужен не только в локальном окружении разработчика, но и в тестовом где-то на далёком и доступном всем тестировщикам сервере. Для этого мы развернули его на отдельном выделенном сервере и теперь вместо http://localhost:8080/validator он доступен по нашему URL сервера - http://validator.url/validator

Путь первый (через nginx) выглядит вот так: в настройках nginx нашей документации добавили директиву location, которая перехватывает запрос и отправляет нашу .json схему валидатору

location ~ ^/swagger/badge(?<debug>/debug)? {
limit_except GET {
deny all;
}

set $proxy_pass http://validator.url/validator$debug;

proxy_buffering off;
proxy_pass $proxy_pass;
proxy_method POST;
proxy_set_header 'Content-Type' 'application/json';

access_by_lua_block {
ngx.req.read_body();

local fd = io.open(ngx.var.root .. "/public/swagger/resources/combinedSchema.json", "r")
if not fd then
ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

schema = fd:read("*a")
if not schema then
ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

ngx.req.set_body_data(schema)
}
}
Путь второй (через php) выглядит как обычная реализация запрос-контроллер-экшн_метод. В запросе к контроллеру GET-параметром придёт url с нашей json схемой и наша задача передать её содержимое валидатору. В ответе с сервера валидатора вернётся изображение-статус валидации. Приблизительно код получается такой:

$schemaUrl = (string) $request->query->get('url');

$schemaRequest = $this->httpClient->request('GET', $schemaUrl);
$schema = $schemaRequest->getContent();

$request = $this->httpClient->request('POST',
'http://validator.url/validator',
[
'body' => $schema,
'headers' => [
'Content-Type' => 'application/json'
]
]
);

$result = $request->getContent();

return new JsonResponse(
utf8_encode($result),
Response::HTTP_OK,
['Content-Type' => 'image/png']
);
Для получения дебаг-информации код будет приблизительно следующим:

$schemaUrl = (string) $request->query->get('url');
$schemaRequest = $this->httpClient->request('GET', $schemaUrl);
$schema = $schemaRequest->getContent();

$request = $this->httpClient->request('POST',
'http://validator.url/validator/debug',
[
'body' => $schema,
'headers' => [
'Content-Type' => 'application/json'
]
]
);

$result = $request->getContent();

return new JsonResponse(
\json_decode($result, true, 512, \JSON_THROW_ON_ERROR),
Response::HTTP_OK
);
На этом всё. Открывая страницу нашей документации в правом нижнем углу должно отображаться изображение со статусом валидации.