EvilBeaver
Генерация доков к веб апи
Захотелось реализовать докген ибо руками генерить доки для того же сваггера лень и постоянная ручная поддержка актуальности приносит много боли.
Выбор пал на сваггер, лично мне он очень нравится + можно конвертить через какой нибуть https://apimatic.io/transformer во что угодно, так же через сервисы сваггера можно генерить клиенты \ сервера по описанию api + мокать можно без кодирования через сваггер хаб..) в общем плюшек много
Как генератор будет поставляться (через либу или в составе ос.веб) дело третье. А вот как прикрутить нормально к языку пока придумать не могу, тот же генератор для C# больше половины сведений берет через рефлексию ибо статическая типизация все дела, не надо особо ничего писать в атрибутах \ комментах.
С динамическим есть пример того же php, где уже запилен генератор и имхо выглядет просто отвратительно, данные добавляются через комментарии в которых содержатся аннотации через "@"
тут вот пример https://github.com/zircote/swagger-php/blob/master/Examples/petstore-3.0/controllers/Pet.php
Получить, что в среднестатистичеком контроллере весь код будет состоять из комментариев к сваггеру :) Собственно я пока не могу придумать ничего лучше и хочу коллективно это обсудить может сделаем для нашей платформы что-то получше.
Наверное что-то надо, но я не сталкивался со сваггером никогда. Надо погружаться. Есть кто-то более знающий?
@asosnoviy @nixel2007??
Из коробки сваггер поддерживает документацию в виде внешнего yml файла. По ней собственно и генерит сайт/описание/моки и прочее.
С учётом сложности движка не думаю, что получится сделать это какой-то внешней либой без выброса наружу из движка описания модели текущего приложения. Либо же эта генерация описания для swagger (точнее уже openapi) будет заложена в сам движок сайта каким-то новым флагом самого ехешника (кажется, внутри движка это называется behavior)
Тоже подумал будет просто))
Но с наскока не вышло ибо в core версии asp как оказалась довольно успешно выпиливается поддержка convention роутинга, в частности проекты которые уже сделаны для генерации в сваггер работают через ApiExplorer, а он при активации шлет лесом говоря, что не поддерживает данный тип роутинга.
Искал офф инфу, но пока ничего не пишут, в комментариях к некоторым ишузам в aspшном репо команда разработки так и отписывалась, "активная поддержка convention роутинга прекращена, юзайте роутинг через атрибуты (это [Route("api/xxx")] которые)".
В целом покапавшись в исходниках ASP, я обошел это ограничение, ошибки нет, но генератор не выдает методы контроллеров((
Собственно @EvilBeaver @nixel2007 2 вопроса:
Будет ли меняться в ближайщее время механизм роутинга или нет? Будет ли принята данная фича в состав проекта? ибо без включения в проект завести все это не получится, а поддерживать форк у меня времени нет.
@ArchLord42RU а переопределение маршрутов через функцию-обработчик к какому типу роутинга относится? convention? или какого-то третьего типа? (просто это явно не аттрибуты :) )
По вопросу 2: главный тут @EvilBeaver, но думаю, что не ошибусь, если скажу что любая фича, особенно продвигающая стандартизацию и спецификацию, будет полезна для проекта и будет в него включена. сейчас у проекта чертовски мало контрибьюторов, любая помощь - это очень и очень здорово
@nixel2007
а переопределение маршрутов через функцию-обработчик к какому типу роутинга относится? convention? или какого-то третьего типа? (просто это явно не аттрибуты :) )
это custom convention видимо :)
Я олдскульный юзер АСП. В мои годы роутинг на атрибутах считался ересью. Поэтому я начал с того, что знаю и понимаю. А так -да, конечно роутинг на атрибутах будет и нужен.
он у меня уже работает в контексте этой фичи, но я тогда декомпозирую ее и скину сначал роутинг, как с тестами разберусь, а потом эту фичу отдельно кину.
В ASP у ActionModel есть нечто под названием IApiExplorer. Кажется, надо покопаться там.
В ASP у ActionModel есть нечто под названием IApiExplorer. Кажется, надо покопаться там.
Да это интерфейс генерации описания API в ASP который работает на основе IApiDescriptionProvider и IApiDescriptionGroupCollectionProvider.
Это фундамент на базе которого работаю остальные проекты в моем случае Swashbuckle, тут уже будет не важно, что прикручивать ибо любой генератор будет включаются в пару строк кода в statup.cs, главное адекватная поддержка интефейса генерации, но документация к нему чуть более чем полностью отсуствует и только исходники ASP помогают.
Вчера довел до рабочего состояния IApiExplorer, но пока не понял, что конкретно я накодил, чтобы он работал)) Для меня, видящего ASP в принципе в первый раз в жизни (а уж тем более его исходники) это пока как космический корабль.
@ArchLord42RU в таком случае, присылай реквест с пометкой WIP и галочкой allow edits from maintainers и будем вместе смотреть