Комментарии 12
Проблема очень знакома, пишем долгое время документацию вручную, времени съедает много, часто случается что забыли что-то обновить, в общем не рабочее решение.
Сейчас разрабатываю rest-api-bundle для Symfony и тоже хочу реализовать там автогенерацию документации swagger. Но я пошёл другим путем, запросы и ответы в бандле описываются в виде классов, а уже по этим классам будет генерироваться json схема.
Сейчас разрабатываю rest-api-bundle для Symfony и тоже хочу реализовать там автогенерацию документации swagger. Но я пошёл другим путем, запросы и ответы в бандле описываются в виде классов, а уже по этим классам будет генерироваться json схема.
0
Nelmio api doc bundle умеет генерировать документацию из аннотаций и может работать в паре с rest api bundle для симфони . Заодно можно получить sandbox на халяву так сказать. И писать ничего не надо, прямо пишем метод, в аннотациях к нему пишем документацию и эту документацию сразу преобразуем в html используя этот бандл
0
Спасибо. Оба решения видел, но мне они не зашли, на мой взгляд, можно лучше.
0
Как ни странно, всегда можно лушче (я ещё ни разу не видел код, который нельзя улучшить), я не касаюсь [sarcasm]фатальных недостатков ПО (типа код написан не нами и код написан не на нашем любимом языке программирования)[/sarcasm]. В данном случае, если не зашли, то можно почерпнуть оттуда сведения чтобы обойти все грабли, на которые люди уже наступили в этих проектах, ну и знание какие варианты вообще есть. А вообще писать что-то своё всегда полезно, хотя бы просто для понимания.
0
Эти классы описывают входные и выходные параметры action'ов? То есть вместо request на вход, там какой-то класс, на выход вместо прямой записи в response body там тоже какой-то класс. А как вы, в таком случае, будете обрабатывать ошибочные случаи?
0
Я думал автогенерация документации и всяких 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 с описанием)
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 с описанием)
0
Эти классы описывают входные и выходные параметры 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) Ошибки бизнес логики – это ошибки которые нужно показать пользователю, они тоже делаются через эксепшены, одна ошибка – один класс. Внутри каждого эксепшена можно указать константу для перевода, либо покажется дефолтный текст.
0
Про обработку ошибок я скорее в контексте добавления их в спецификацию
0
Добавление ошибок бизнес логики?
Они все единого формата, т.е. на них у клиентов универсальный обработчик, соответственно и в документации такое не описываем.
А если все же на основе какой-то ошибки нужно построить логику – то этот момент пойдет уже в другой тип документации, в которой текстом описано как работать с методами и решать задачи.
Они все единого формата, т.е. на них у клиентов универсальный обработчик, соответственно и в документации такое не описываем.
А если все же на основе какой-то ошибки нужно построить логику – то этот момент пойдет уже в другой тип документации, в которой текстом описано как работать с методами и решать задачи.
0
Мы придумали решение (собственный велосипед)
Есть ли у этого велосипеда ссылочка на Github?)
Кстати, для Laravel есть такое github.com/RonasIT/laravel-swagger
А еще на Хабре есть вот такая статья и библиотека в ней habr.com/ru/post/358528, концептуально практически идеальный вариант)
0
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Генерация OpenAPI спецификации на основе функциональных тестов