Что? Зачем?

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

На этом всё. Открывая страницу нашей документации в правом нижнем углу должно отображаться изображение со статусом валидации.

Надежды на светлое будущее

Этот тернистый путь мы проделали сами и надеемся, что вам он поможет сэкономить время, деньги и терпение.

Настройкой сервера валидатора и написанием кода занимался не я один, а с помощью Михаила Даниленко и Ольги Демчишиной.

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