Генерация OpenAPI спецификации на основе функциональных тестов

[lowadka]

Проблема очень знакома, пишем долгое время документацию вручную, времени съедает много, часто случается что забыли что-то обновить, в общем не рабочее решение.

Сейчас разрабатываю rest-api-bundle для Symfony и тоже хочу реализовать там автогенерацию документации swagger. Но я пошёл другим путем, запросы и ответы в бандле описываются в виде классов, а уже по этим классам будет генерироваться json схема.

[Chrome]

Nelmio api doc bundle умеет генерировать документацию из аннотаций и может работать в паре с rest api bundle для симфони . Заодно можно получить sandbox на халяву так сказать. И писать ничего не надо, прямо пишем метод, в аннотациях к нему пишем документацию и эту документацию сразу преобразуем в html используя этот бандл

[lowadka]

Спасибо. Оба решения видел, но мне они не зашли, на мой взгляд, можно лучше.

[Chrome]

Как ни странно, всегда можно лушче (я ещё ни разу не видел код, который нельзя улучшить), я не касаюсь [sarcasm]фатальных недостатков ПО (типа код написан не нами и код написан не на нашем любимом языке программирования)[/sarcasm]. В данном случае, если не зашли, то можно почерпнуть оттуда сведения чтобы обойти все грабли, на которые люди уже наступили в этих проектах, ну и знание какие варианты вообще есть. А вообще писать что-то своё всегда полезно, хотя бы просто для понимания.

[FJCrux]

Эти классы описывают входные и выходные параметры action'ов? То есть вместо request на вход, там какой-то класс, на выход вместо прямой записи в response body там тоже какой-то класс. А как вы, в таком случае, будете обрабатывать ошибочные случаи?

[pawnhearts]

Я думал автогенерация документации и всяких swagger`ов — стандартная фича любого rest фреймворка. В любом случае есть же какой-то сериализатор/валидатор входных данных. И сериализатор выходных, надо же как-то данные из бд преобразовывать в json. В них достаточно данных для создания доков плюс докстринги.

github.com/marshmallow-code/apispec github.com/maximdanilchenko/aiohttp-apispec www.django-rest-framework.org/topics/documenting-your-api (и у каждого поля есть www.django-rest-framework.org/api-guide/fields/#help_text с описанием)

[FJCrux]

Ваши примеры, на самом деле, заставляют разработчика дополнительно описать какие-то описания и аннотации, а мы хотел избавиться от этого.
В нашем случае, у нас всегда должны быть тесты. А вот аннотаций для документации может не быть, а чтобы их писать, нужно изменить процесс разработки

[lowadka]

Эти классы описывают входные и выходные параметры action'ов

Все верно, реквест модели выглядят примерно вот так:

Пример

<?php

namespace App\AcmeBundle\RequestModel;

use RestApiBundle\Annotation\RequestModel as Mapper;
use Symfony\Component\Validator\Constraints as Assert;
use RestApiBundle\RequestModelInterface;

class CreateMovie implements RequestModelInterface
{
    /**
     * @var string
     *
     * @Mapper\StringType()
     * @Assert\Length(min=3)
     */
    private $name;

    /**
     * @var string[]|null
     *
     * @Mapper\CollectionType(type=@Mapper\StringType(), nullable=true)
     */
    private $genres;
    
    ... getters and setters
}

А как вы, в таком случае, будете обрабатывать ошибочные случаи

Ошибок есть всего грубо говоря 3 вида:
1) Ошибки валидации/маппинга реквест модели – это бандл обработает сам и вернет клиенту ошибку, т.е. внутри action доступна уже чистая модель
2) Уникальные ошибки – это ошибки с каким-то своим поведением, например 404, 403 и тд, они отлавливаются и отдается json response вместо них + статус
3) Ошибки бизнес логики – это ошибки которые нужно показать пользователю, они тоже делаются через эксепшены, одна ошибка – один класс. Внутри каждого эксепшена можно указать константу для перевода, либо покажется дефолтный текст.

[FJCrux]

Про обработку ошибок я скорее в контексте добавления их в спецификацию

[lowadka]

Добавление ошибок бизнес логики?

Они все единого формата, т.е. на них у клиентов универсальный обработчик, соответственно и в документации такое не описываем.

А если все же на основе какой-то ошибки нужно построить логику – то этот момент пойдет уже в другой тип документации, в которой текстом описано как работать с методами и решать задачи.

[FJCrux]

На них вряд ли стоит строить БЛ, но у нас была потребность показать пользователю, какие от данной команды можно ожидать неуспешные результаты (и сказать, что они значат, чтобы он мог это поправить)

[Vumik]

Мы придумали решение (собственный велосипед)

Есть ли у этого велосипеда ссылочка на Github?)

Кстати, для Laravel есть такое github.com/RonasIT/laravel-swagger

А еще на Хабре есть вот такая статья и библиотека в ней habr.com/ru/post/358528, концептуально практически идеальный вариант)