#tw_api_jekyll
Всем привет.
Продолжаем знакомство с Jekyll. В прошлый раз мы вывели (пока не совсем в удобочитаемом виде) содержимое спецификации API на сайт.
Давайте начнем приводить все в более-менее приятный вид. Сегодня мы:
- Посмотрим на документацию OpenAPI Specification.
- Выведем на сайт некоторые поля «первого» уровня схемы API.
Спецификация API (у нас она размещена в файле _data/openapi_spec.yaml) пишется в соответствии с определенным набором правил. И для OpenAPI это набор правил — OpenAPI Specification соответствующей версии (в нашем случае это OpenAPI Specification V 3.0.0). В ней рассмотрено, что должна (и может) содержать спецификация API, и как это все описать. То есть если мы взялись писать генератор справочника API из OpenAPI-спецификации в формате OpenAPI Specification V 3.0.0, без ее изучения не обойтись (это вам задание на дом).
Если пробежаться по OpenAPI Specification V 3.0.0, становится видно, что спецификация API (напоминаю, что у нас это _data/openapi_spec.yaml) — это один большой объект, который включает поля разных типов. И чтобы отрендерить нужную нам информацию (поля объекта), нужно обратиться к этим полям в скрипте _includes/api_reference.liquid, которым мы в предыдущем посте выводили схему на страницу, и обработать их удобным нам способом.
Вывод полей «первого» уровня на сайт
Если посмотреть документацию OpenAPI Specification V 3.0.0, вы увидите, что спецификация API содержит фиксированный набор полей. Часть из них обязательные (openapi, info и paths), другие — нет.
При подготовке сегодняшнего поста, для наглядности, я добавил в нашу спецификацию _data/openapi_spec.yaml поле servers (необязательное), чтобы потренироваться в выводе обязательных и необязательных полей страницу нашего сайта-справочника. И вы его себе тоже можете добавить.
Итак, давайте выведем на страницу поля «первого уровня»:
- openapi,
- info,
- servers.
Остальными займемся в следующих постах.
Для этого измените файл _includes/api_reference.liquid.
Содержимое тега замените на:
{{ spec.info['title'] }}
Версия API: {{ spec.info['version'] }}
Описание API:
{{ spec.info.['description'] | markdownify }}
{% if spec.servers %}
Список серверов:
{% for server in spec.servers %}
{{ server.['description'] }}: {{ server.['url'] }}
{% endfor %}
{% endif %}
Что здесь происходит (поясняю некоторые фрагменты, т.к. для большинства одинаковая механика)?
- {{ spec.info['title'] }} — рендерится содержимое поля title обязательного поля (объекта) info.
- В условии {% if spec.servers %} ... {% endif %} проверяется наличие в спецификации поля servers (согласно спецификации это — массив).
- Если поле servers существует в спецификации, рендерится его содержимое. Для этого используется цикл {% for server in spec.servers %} ... {% endfor %}, который проходит во всем элементам массива servers. и выводит их содержимое на страницу.
Что еще нужно сделать на этом этапе
Со страницы index.md можете убрать заголовок. Он не нужен, ведь в качестве заголовка страницы выводится содержимое поля info.title.
Готово. Если вы все сделали правильно, часть содержимого спецификации появится на странице сайта (не забываем, про bundle exec jekyll serve).
Пока без CSS: этим займемся на следующих этапах.
Свериться с результатом, который должен получиться, можно в ветке iteration_3.
Всем привет.
Продолжаем знакомство с Jekyll. В прошлый раз мы вывели (пока не совсем в удобочитаемом виде) содержимое спецификации API на сайт.
Давайте начнем приводить все в более-менее приятный вид. Сегодня мы:
- Посмотрим на документацию OpenAPI Specification.
- Выведем на сайт некоторые поля «первого» уровня схемы API.
Спецификация API (у нас она размещена в файле _data/openapi_spec.yaml) пишется в соответствии с определенным набором правил. И для OpenAPI это набор правил — OpenAPI Specification соответствующей версии (в нашем случае это OpenAPI Specification V 3.0.0). В ней рассмотрено, что должна (и может) содержать спецификация API, и как это все описать. То есть если мы взялись писать генератор справочника API из OpenAPI-спецификации в формате OpenAPI Specification V 3.0.0, без ее изучения не обойтись (это вам задание на дом).
Если пробежаться по OpenAPI Specification V 3.0.0, становится видно, что спецификация API (напоминаю, что у нас это _data/openapi_spec.yaml) — это один большой объект, который включает поля разных типов. И чтобы отрендерить нужную нам информацию (поля объекта), нужно обратиться к этим полям в скрипте _includes/api_reference.liquid, которым мы в предыдущем посте выводили схему на страницу, и обработать их удобным нам способом.
Вывод полей «первого» уровня на сайт
Если посмотреть документацию OpenAPI Specification V 3.0.0, вы увидите, что спецификация API содержит фиксированный набор полей. Часть из них обязательные (openapi, info и paths), другие — нет.
При подготовке сегодняшнего поста, для наглядности, я добавил в нашу спецификацию _data/openapi_spec.yaml поле servers (необязательное), чтобы потренироваться в выводе обязательных и необязательных полей страницу нашего сайта-справочника. И вы его себе тоже можете добавить.
Итак, давайте выведем на страницу поля «первого уровня»:
- openapi,
- info,
- servers.
Остальными займемся в следующих постах.
Для этого измените файл _includes/api_reference.liquid.
Содержимое тега замените на:
{{ spec.info['title'] }}
Версия API: {{ spec.info['version'] }}
Описание API:
{{ spec.info.['description'] | markdownify }}
{% if spec.servers %}
Список серверов:
{% for server in spec.servers %}
{{ server.['description'] }}: {{ server.['url'] }}
{% endfor %}
{% endif %}
Что здесь происходит (поясняю некоторые фрагменты, т.к. для большинства одинаковая механика)?
- {{ spec.info['title'] }} — рендерится содержимое поля title обязательного поля (объекта) info.
- В условии {% if spec.servers %} ... {% endif %} проверяется наличие в спецификации поля servers (согласно спецификации это — массив).
- Если поле servers существует в спецификации, рендерится его содержимое. Для этого используется цикл {% for server in spec.servers %} ... {% endfor %}, который проходит во всем элементам массива servers. и выводит их содержимое на страницу.
Что еще нужно сделать на этом этапе
Со страницы index.md можете убрать заголовок. Он не нужен, ведь в качестве заголовка страницы выводится содержимое поля info.title.
Готово. Если вы все сделали правильно, часть содержимого спецификации появится на странице сайта (не забываем, про bundle exec jekyll serve).
Пока без CSS: этим займемся на следующих этапах.
Свериться с результатом, который должен получиться, можно в ветке iteration_3.