Блоки

Документация API

Страница документации API: сведения об авторизации и ошибках, оглавление, группы операций с таблицей полей, запросом и ответом.

Примеры

<main class="page"><div class="page__in api">
  <p class="page__back"><a href="#">← К API-токенам</a></p>
  <p class="eyebrow">// meet.bukatchuk.ru/api/v1</p>
  <h1 class="page__h">API видеоконференций</h1>
  <p class="page__lead">Через API скрипты и сервисы управляют встречами и контактами — тем же, что доступно в личном кабинете. Обмен идёт в JSON.</p>
  <div class="api__facts">
    <div class="card">
      <p class="field__label">Авторизация</p>
      <p class="api__text">Каждый запрос несёт токен в заголовке. Токен создаётся в кабинете, в разделе «API-токены».</p>
      <pre class="codebox codebox--sm api__pre">Authorization: Bearer meet_…</pre>
    </div>
    <div class="card">
      <p class="field__label">Ошибки</p>
      <p class="api__text">Ответ с кодом 4xx или 5xx содержит код ошибки и пояснение. Неверные поля — код 422.</p>
      <pre class="codebox codebox--sm api__pre">{"error": {"code": "unauthorized"}}</pre>
    </div>
    <div class="card">
      <p class="field__label">Даты</p>
      <p class="api__text">Даты в ответах — UTC в формате ISO 8601.</p>
      <pre class="codebox codebox--sm api__pre">2026-12-25T11:30:00Z</pre>
    </div>
  </div>
  <nav class="api__nav" aria-label="Разделы API">
    <a class="api__nav-item" href="#meetings">Встречи <span>2</span></a>
  </nav>
  <section class="api__group" id="meetings">
    <h2 class="subhead">Встречи</h2>
    <p class="api__text">Создание и просмотр встреч текущего пользователя.</p>
    <article class="api__op" id="meetings-create">
      <header class="api__op-head">
        <span class="api__method api__method--post">POST</span>
        <code class="api__path">/api/v1/meetings</code>
        <span class="api__summary">Создать встречу</span>
      </header>
      <div class="api__op-body">
        <div class="table-wrap"><table class="table api__table">
          <thead><tr><th>Поле</th><th>Тип</th><th>Описание</th></tr></thead>
          <tbody>
            <tr><td><code>title</code><br><small class="api__req">обязательное</small></td><td>строка<br><small>до 120 символов</small></td><td>Название встречи.</td></tr>
            <tr><td><code>starts_at</code></td><td>дата и время</td><td>Начало в формате ISO 8601.</td></tr>
          </tbody>
        </table></div>
        <div class="api__cols">
          <div class="api__col">
            <p class="field__label">Запрос <button class="btn btn--sm btn--ghost api__copy" type="button" data-ui-copy="curl -X POST https://meet.bukatchuk.ru/api/v1/meetings" data-ui-copied="Скопировано">Скопировать</button></p>
            <pre class="api__term">curl -X POST https://meet.bukatchuk.ru/api/v1/meetings</pre>
          </div>
          <div class="api__col">
            <p class="field__label">Ответ <span class="badge badge--ok">201</span></p>
            <pre class="codebox codebox--sm api__pre">{"id": 42, "title": "Планёрка"}</pre>
            <p class="field__hint">Созданная встреча.</p>
          </div>
        </div>
      </div>
    </article>
  </section>
</div></main>

Установка

bukatchuk-ui add api-docs

Файлы

Макрос для Jinja

{#- Страница документации API. facts — список (title, text, sample); groups — список групп с полями
    anchor, title, note и operations (anchor, method, path, summary, params, fields, curl, status, example, returns). -#}
{% macro api_docs(title, lead, groups, facts=[], eyebrow='', back=None, back_text='← Назад') -%}
<main class="page"><div class="page__in api">
  {%- if back %}
  <p class="page__back"><a href="{{ back }}">{{ back_text }}</a></p>
  {%- endif %}
  {%- if eyebrow %}
  <p class="eyebrow">{{ eyebrow }}</p>
  {%- endif %}
  <h1 class="page__h">{{ title }}</h1>
  <p class="page__lead">{{ lead }}</p>
  {%- if facts %}
  <div class="api__facts">
    {%- for f in facts %}
    <div class="card">
      <p class="field__label">{{ f.title }}</p>
      <p class="api__text">{{ f.text }}</p>
      <pre class="codebox codebox--sm api__pre">{{ f.sample }}</pre>
    </div>
    {%- endfor %}
  </div>
  {%- endif %}
  <nav class="api__nav" aria-label="Разделы API">
    {%- for g in groups %}<a class="api__nav-item" href="#{{ g.anchor }}">{{ g.title }} <span>{{ g.operations|length }}</span></a>{% endfor %}
  </nav>
  {%- for g in groups %}
  <section class="api__group" id="{{ g.anchor }}">
    <h2 class="subhead">{{ g.title }}</h2>
    {%- if g.note %}<p class="api__text">{{ g.note }}</p>{% endif %}
    {%- for op in g.operations %}
    <article class="api__op" id="{{ op.anchor }}">
      <header class="api__op-head">
        <span class="api__method api__method--{{ op.method|lower }}">{{ op.method }}</span>
        <code class="api__path">{{ op.path }}</code>
        <span class="api__summary">{{ op.summary }}</span>
      </header>
      <div class="api__op-body">
        {%- if op.params or op.fields %}
        <div class="table-wrap"><table class="table api__table">
          <thead><tr><th>Поле</th><th>Тип</th><th>Описание</th></tr></thead>
          <tbody>
            {%- for p in op.params %}<tr><td><code>{{ p.name }}</code><br><small>в адресе</small></td><td>целое число</td><td>{{ p.description }}</td></tr>{% endfor %}
            {%- for f in op.fields %}<tr>
              <td><code>{{ f.name }}</code>{% if f.required %}<br><small class="api__req">обязательное</small>{% endif %}</td>
              <td>{{ f.type }}{% if f.limits %}<br><small>{{ f.limits }}</small>{% endif %}</td>
              <td>{{ f.description }}{% if f.default is not none %} <small>По умолчанию: {{ f.default }}.</small>{% endif %}</td>
            </tr>{% endfor %}
          </tbody>
        </table></div>
        {%- endif %}
        <div class="api__cols">
          <div class="api__col">
            <p class="field__label">Запрос <button class="btn btn--sm btn--ghost api__copy" type="button" data-ui-copy="{{ op.curl }}" data-ui-copied="Скопировано">Скопировать</button></p>
            <pre class="api__term">{{ op.curl }}</pre>
          </div>
          <div class="api__col">
            <p class="field__label">Ответ <span class="badge badge--ok">{{ op.status }}</span></p>
            {%- if op.example %}<pre class="codebox codebox--sm api__pre">{{ op.example }}</pre>{% endif %}
            <p class="field__hint">{{ op.returns }}.</p>
          </div>
        </div>
      </div>
    </article>
    {%- endfor %}
  </section>
  {%- endfor %}
</div></main>
{%- endmacro %}