EvilBeaver
WIP: Поддержка генератора документации
#47
Пока я собрался сделать ПР. @EvilBeaver уже добавил поддержку роутинга по атрибутам и корректное заполнение селекторов, что сильно облегчило внедрение.
Генератор работает на основе проекта Swashbuckle https://github.com/domaindrivendev/Swashbuckle.AspNetCore
Сейчас работает UI и генератор JSON для сваггера.
Модуль включается через метод "ИспользоватьДокументацию" по аналогии с "ИспользоватьМаршруты"
UI доступен по адресу host:port/swagger JSON для UI находится по адресу host:port/swagger/{version}/swagger.json Метаданные, включая версию вынес в конфиг файл (в нашем случае appsettings.json), в секцию "Info", структуру глянуть пока тут https://github.com/ArchLord42RU/OneScript.Web/blob/e706537104aaeb69e049e7e39fe4e3249d3ae8e3/src/OneScript/Infrastructure/SwaggerServicePlugin.cs Видны только методы помеченные аннотацией Route\Маршрут(xxx)
Замеченные проблемы:
-
Нет описания возвращаемого значения, точней оно всегда ActionResult
-
Все методы имеют OperationId "ResultAction" (автоматом присваивается имя метода), не очень страшно, но UI тупит из-за этого, если сделать маппинг на OS методы, то хз как там будет с кириллицей.
-
Для UI сейчас захардкожен добавленный эндпоинт, надо бы его из конфига грузить. https://github.com/EvilBeaver/OneScript.Web/compare/develop...ArchLord42RU:feature/Swagger?expand=1#diff-cf462c11ed5d57c1216462ff171014f7R199
-
Нет поддержки версионированного описания API (а надо ли?)
Это что-то явно крутое, мне надо время, чтобы въехать. К выходным думаю, доберусь. Спасибо!
Собственно я в первом сообщении написал что там еще надо. Пока у самого руки не дошли( Щас доки генерятся, но толку от них особого нет ибо:
- Нет маппинга возвращаемого значения из ОСкрипта
- Нет маппинга входящих параметров из ОСкрипта
Тут надо по большей части надо порассуждать \ попробывать как удобней писать код и сделать верное архитектурное решение как все это прокинуть в APIExplorer из ОСкрипта
Начнем с 1.
В шарпе все довольно просто ибо статическая типизация, он например смотрит что тип возр. значения у хттп метода "Pet", он читает все публичные свойства и делает "модель" (в терминах сваггера) и потом в документации мы видим что-то типа того
В Оскрипте такой финт не прокатит ибо дин.типизация, в пхп юзают комменты вида "@Return Pet" как то так, где Pet это пхпшный класс.
Можно так же сделать аннотацию &Возврат("Pet") а там уже считать свойства
В свою очередь в классе Pet будут свойства опять же с аннотациями типа:
&Тип("string")
Перем Id Экспорт;
чтобы все типы значений прокинулись корректно.
Тут мы конечно будем вынуждены, если нам нужен генератор отказаться от
Возврат Новый Структура("Id", 1);
Но структуру обработать гораздо сложнее будет.
А можно пойти путем 1Сным и спарсить типичный коммент для процедур \ функций Это которые такие:
// Описание функции (хттп метода)
//
// Параметры:
// Нет
//
// Возвращаемое значение:
// Класс - Pet
//
или такие
// Описание функции (хттп метода)
//
// Параметры:
// Нет
//
// Возвращаемое значение:
// Структура
// * Id Строка - Идентификатор блаблабла
//
А как же возврат представлений/результатов? Да ещё и динамический иногда: если все хорошо, то вьюха, а иначе 500?
@nixel2007
Сваггер же больше про документацию АПИ, а какие там вьюхи. Хотя видел как-то, что из апи возвращался хтмл, правда 1 раз. Если рассмотреть данную ситуацию с точки зрения типов данных, то вьюха это хтмл, а хтмл это строка, собственно
//Блаблабла
// Возвращаемое значение:
// Строка - представление чего-то там
Кстати в документации сваггера возвращаемый тип "файл" тоже имеет тип строка с форматом binary или byte. Да и у сваггера есть ограничение на типы данных, их не так много, только основные https://swagger.io/docs/specification/data-models/data-types/
Возврат кодов состояний можно сделать так:
//Блаблабла
// Возвращаемое значение:
// Структура
// * Id Строка - Идентификатор блаблабла
// Код состояния
// * 404 - Элемент не найден
// * 400 - Не верные чего-то там
@nixel2007
А так первое прям попахивает entity :)
Сначала подумал про entity framework, а потом вспомнил, что мне на инфостарте Лустин или Сосновый говорил про твой ОРМ, это ты его и имел ввиду как я понял))
Вообще может не с того места зашел, вместо внедрения в код самого проекта, можно было бы сделать возможность добавлять "плагины" для движка, которые бы имели доступ в ConfigureServices \ Configure, а там уже делай что хочешь, тогда можно бы было сделать все тоже самое, что я и щас сделал, но вынести логику генерации в оскрипт, а тут мы уже имеем https://github.com/bia-tech/autodocgen и твой entity. Соответсвенно сама логика генерации была бы в оскрипте, где больше свободы для конечного разработчика, ну и результат бы отдавался в провайдер сваггера. И поствлять в виде либы.
@EvilBeaver что думаешь?
@ArchLord42RU я понимаю про swagger. я скорее про то, что oscript.web - это не только голые http-сервисы, возвращающие данные (то бишь бэкэнд). это еще и фреймворк для построения приложений. первый пример - odminus, который веб-обертка над rac.
Сначала подумал про entity framework, а потом вспомнил, что мне на инфостарте Лустин или Сосновый говорил про твой ОРМ, это ты его и имел ввиду как я понял))
да, его) просто аннотации с типами над переменными класса - это прям оно :)
в целом идея со сваггером очень клевая и полезная! просто нужно учесть особенности фреймворка.
@ArchLord42RU я понимаю про swagger. я скорее про то, что oscript.web - это не только голые http-сервисы, возвращающие данные. это еще и фреймворк для построения приложений. первый пример - odminus, который веб-обертка над rac.
вот в том то и дело, сваггер штука узкоспециализированная и изначально я думал как сделать так, чтобы его небыло в основном проекте ибо нужно оно будет не такому большому количеству людей.
@ArchLord42RU я могу тебе просто дать права на пуш в этот проект и ты будешь не пулреквестить, а напрямую пилить в движок?
Тут явно много экспериментирования потребуется, поэтому открытие/обсуждение реквестов, кажется преждевременным. Такое удобно, когда уже есть видение по той или иной теме. Здесь его нет и удобнее просто кодить и смотреть что получается, не?
@nixel2007 ну можно и так, тут щас главное заиметь время на эксперименты) Я вот уже месяц прикручиваю ОСкрипт к Астериску через ARI, собственно буквально вчера добился более менее внятного синтаксиса со стороны ОСкрипта, при этом я не в свободное время делаю а в рабочее, т.к. проект для нужд компании.
@EvilBeaver я думаю он имеет ввиду текущую ветку закинуть в основной репо и с ней продолжить работать.
Именно.
Отправлено с помощью BlueMail
На 26 нояб. 2018 г., 0:52, в 0:52, Dmitriy Korolev [email protected] написал:п>@EvilBeaver я думаю он имеет ввиду текущую ветку закинуть в основной
репо и с ней продолжить работать.
-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/EvilBeaver/OneScript.Web/pull/48#issuecomment-441458825
Вам чиз одним писом или наслайсить? (с)
Отправлено с помощью BlueMail
На 26 нояб. 2018 г., 0:16, в 0:16, Andrei Ovsiankin [email protected] написал:п>> Можно просто эту же ветку запушить в другой ремоут
Чо-чо сделать?
-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/EvilBeaver/OneScript.Web/pull/48#issuecomment-441456315
@EvilBeaver оп, я только что занотайсил, что экстеншены уже сделаны лонг тайм эгоу :) это который ExtensionsCompiler, только что-то не пойму не доделано оно? Кроме как в тесте работу с данным классом нигде не вижу.