Генерация доков к веб апи

[dvakor]

Захотелось реализовать докген ибо руками генерить доки для того же сваггера лень и постоянная ручная поддержка актуальности приносит много боли.

Выбор пал на сваггер, лично мне он очень нравится + можно конвертить через какой нибуть
https://apimatic.io/transformer
во что угодно, так же через сервисы сваггера можно генерить клиенты \ сервера по описанию api + мокать можно без кодирования через сваггер хаб..) в общем плюшек много

Как генератор будет поставляться (через либу или в составе ос.веб) дело третье.
А вот как прикрутить нормально к языку пока придумать не могу, тот же генератор для C# больше половины сведений берет через рефлексию ибо статическая типизация все дела, не надо особо ничего писать в атрибутах \ комментах.

С динамическим есть пример того же php, где уже запилен генератор и имхо выглядет просто отвратительно, данные добавляются через комментарии в которых содержатся аннотации через "@"

тут вот пример
https://github.com/zircote/swagger-php/blob/master/Examples/petstore-3.0/controllers/Pet.php

Получить, что в среднестатистичеком контроллере весь код будет состоять из комментариев к сваггеру :)
Собственно я пока не могу придумать ничего лучше и хочу коллективно это обсудить может сделаем для нашей платформы что-то получше.

[EvilBeaver]

Наверное что-то надо, но я не сталкивался со сваггером никогда. Надо погружаться. Есть кто-то более знающий?

@asosnoviy @nixel2007??

[nixel2007]

Из коробки сваггер поддерживает документацию в виде внешнего yml файла. По ней собственно и генерит сайт/описание/моки и прочее.

С учётом сложности движка не думаю, что получится сделать это какой-то внешней либой без выброса наружу из движка описания модели текущего приложения. Либо же эта генерация описания для swagger (точнее уже openapi) будет заложена в сам движок сайта каким-то новым флагом самого ехешника (кажется, внутри движка это называется behavior)

[EvilBeaver]

выбросить json-модель из приложения в принципе, думаю, будет не сложно.

[dvakor]

Тоже подумал будет просто))

Но с наскока не вышло ибо в core версии asp как оказалась довольно успешно выпиливается поддержка convention роутинга, в частности проекты которые уже сделаны для генерации в сваггер работают через ApiExplorer, а он при активации шлет лесом говоря, что не поддерживает данный тип роутинга.

Искал офф инфу, но пока ничего не пишут, в комментариях к некоторым ишузам в aspшном репо команда разработки так и отписывалась, "активная поддержка convention роутинга прекращена, юзайте роутинг через атрибуты (это [Route("api/xxx")] которые)".

В целом покапавшись в исходниках ASP, я обошел это ограничение, ошибки нет, но генератор не выдает методы контроллеров((

Собственно @EvilBeaver @nixel2007 2 вопроса:

Будет ли меняться в ближайщее время механизм роутинга или нет?
Будет ли принята данная фича в состав проекта? ибо без включения в проект завести все это не получится, а поддерживать форк у меня времени нет.

[nixel2007]

@Archlord42Ru а переопределение маршрутов через функцию-обработчик к какому типу роутинга относится? convention? или какого-то третьего типа? (просто это явно не аттрибуты :) )

[nixel2007]

По вопросу 2: главный тут @EvilBeaver, но думаю, что не ошибусь, если скажу что любая фича, особенно продвигающая стандартизацию и спецификацию, будет полезна для проекта и будет в него включена. сейчас у проекта чертовски мало контрибьюторов, любая помощь - это очень и очень здорово

[dvakor]

@nixel2007

а переопределение маршрутов через функцию-обработчик к какому типу роутинга относится? convention? или какого-то третьего типа? (просто это явно не аттрибуты :) )

это custom convention видимо :)

[EvilBeaver]

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

[dvakor]

он у меня уже работает в контексте этой фичи, но я тогда декомпозирую ее и скину сначал роутинг, как с тестами разберусь, а потом эту фичу отдельно кину.

[EvilBeaver]

В ASP у ActionModel есть нечто под названием IApiExplorer. Кажется, надо покопаться там.

[dvakor]

В ASP у ActionModel есть нечто под названием IApiExplorer. Кажется, надо покопаться там.

Да это интерфейс генерации описания API в ASP который работает на основе IApiDescriptionProvider и IApiDescriptionGroupCollectionProvider.

Это фундамент на базе которого работаю остальные проекты в моем случае Swashbuckle, тут уже будет не важно, что прикручивать ибо любой генератор будет включаются в пару строк кода в statup.cs, главное адекватная поддержка интефейса генерации, но документация к нему чуть более чем полностью отсуствует и только исходники ASP помогают.

Вчера довел до рабочего состояния IApiExplorer, но пока не понял, что конкретно я накодил, чтобы он работал)) Для меня, видящего ASP в принципе в первый раз в жизни (а уж тем более его исходники) это пока как космический корабль.

[EvilBeaver]

@Archlord42Ru в таком случае, присылай реквест с пометкой WIP и галочкой allow edits from maintainers и будем вместе смотреть

[dvakor]

Выходные кончились, время тоже(( На выходных кину