#tw_api_jekyll Всем привет. Давно не было новостей про наш сайт-справочник API на базе Jekyll. А их поднакопилось с прошлого раза. Рассказываю, что изменилось. Liquid-код разнесен по нескольким файлам Количество строк кода неуклонно растет, поэтому было принято решение разнести его по отдельным файлам. Так все будет легче обслуживать. «Главным» файлом остается _includes/api_reference.liquid. В папку _includes добавлены несколько файлов, которые инклюдятся в «главный». Например, код для рендеринга эндпоинтов переехал в _includes/endpoints.liquid и иклюдится в файле api_reference.liquid так: {%- include endpoints.liquid -%} В папке _includes также появились файлы api_components.liquid (с кодом для рендеринга компонентов) и request_body.liquid (рендеринг тела запроса для методов). Рендеринг параметров стал лучше Теперь сайт умеет рендерить не только параметры, описанные прямо в описании метода, но описанные в компонентах и передающиеся по ссылке. За это отвечает фрагмент под комментарием <!-- Рендеринг параметров, которые подтягиваются по ссылке --> в _includes/endpoints.liquid. Здесь интерес представляет код, с помощью которого мы итерируемся по свойствам тела запроса, описанного по ссылке: {% if parameter['&#036;ref'] %} {% assign ref_string = parameter['&#036;ref'] %} {% assign dynamic_path = "spec." | append: ref_string | remove: "#/" | replace: "/", "." %} {% assign path_parts = dynamic_path | split: "." %} {% assign result_object = spec %} {% for part in path_parts %} {% if part != "" and part != "spec" %} {% assign result_object = result_object[part] %} {% endif %} {% endfor %} ... {% if parameter['&#036;ref'] %} Этот код: 1. Преобразует ссылку в путь (пример: "spec.components.schemas.User"). 2. Разбивает путь на части: ["spec", "components", "schemas", "User"]. 3. Последовательно обращается к: spec['components'] → объект components components['schemas'] → объект schemas schemas['User'] → схема User В итоге result_object будет содержать значение, на которое указывает ссылка (например, схему User). Далее мы выводим поля этого объекта в таблицу с параметрами. Реализован вывод тела запроса Это пока зачатки кода для полноценного вывода. Но что-то мы уже умеем. Все происходит в файле _includes/request_body.liquid Здесь есть аналогия с тем, как мы рендерим параметры запроса: описанные в теле и передающиеся по ссылке. Пока реализован рендеринг полей-объектов первого уровня вложенности. Т.е., если в теле есть поле типа object, его содержимое выведется на страницу. А если в этом поле-объекте есть еще вложенное поле-объект, его содержимое ПОКА не рендерится. В будущем добавлю рендеринг еще пары уровней вложенности. Но не больше, т.к. глубокая вложенность для объектов в теле запроса выглядит как лютый антипаттерн в проектировании API. Для рендеринга вложенных полей объекта я не использовал рекурсию: все довольно просто («ифчики» и циклы). Это опять же по причине того, что нам большая вложенность не нужна. Да и если рекурсивно вызывать какой-то код с передачей ему параметров, будет создаваться новый контекст, что «пожирает» память. Тело запроса рендерится пока некрасиво. В будущем мы это поправим и сделаем здесь функциональность сворачивания/разворачивания. Реализованы другие функции и возможности Среди них: - Вывод на страницу компонентов. Пока совсем некрасиво, но будет правиться. - Обрезание длинных путей эндпоинтов в меню слева. Если путь не вмещается в меню, появляется многоточие. При наведении на него все отображается полностью. За это отвечает CSS: .schema-toc_link { display: block; white-space: nowrap; overflow: hidden; margin-top: 5px; margin-bottom: 5px; text-overflow: ellipsis; min-width: 14vw; } - Мелкие стилистические правки. Свериться с результатом можно в ветке iteration_7 репозитория под текущую серию постов. И не забываем, про возможность просмотра результата на GitHub Pages.