#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['$ref'] %}
{% assign ref_string = parameter['$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['$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.
Всем привет.
Давно не было новостей про наш сайт-справочник 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['$ref'] %}
{% assign ref_string = parameter['$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['$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.