dvakor commented 6 years ago

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 (а надо ли?)

EvilBeaver commented 6 years ago

Это что-то явно крутое, мне надо время, чтобы въехать. К выходным думаю, доберусь. Спасибо!

EvilBeaver commented 5 years ago

Кстати, раз это WIP - с чем помочь?

dvakor commented 5 years ago

Собственно я в первом сообщении написал что там еще надо. Пока у самого руки не дошли( Щас доки генерятся, но толку от них особого нет ибо:

1) Нет маппинга возвращаемого значения из ОСкрипта 2) Нет маппинга входящих параметров из ОСкрипта

Тут надо по большей части надо порассуждать \ попробывать как удобней писать код и сделать верное архитектурное решение как все это прокинуть в APIExplorer из ОСкрипта

Начнем с 1.

В шарпе все довольно просто ибо статическая типизация, он например смотрит что тип возр. значения у хттп метода "Pet", он читает все публичные свойства и делает "модель" (в терминах сваггера) и потом в документации мы видим что-то типа того

В Оскрипте такой финт не прокатит ибо дин.типизация, в пхп юзают комменты вида "@Return Pet" как то так, где Pet это пхпшный класс.

Можно так же сделать аннотацию &Возврат("Pet") а там уже считать свойства

В свою очередь в классе Pet будут свойства опять же с аннотациями типа:

&Тип("string")
Перем Id Экспорт;

чтобы все типы значений прокинулись корректно. Тут мы конечно будем вынуждены, если нам нужен генератор отказаться от Возврат Новый Структура("Id", 1); Но структуру обработать гораздо сложнее будет.

dvakor commented 5 years ago

А можно пойти путем 1Сным и спарсить типичный коммент для процедур \ функций Это которые такие:

// Описание функции (хттп метода)
//
// Параметры:
//  Нет
//
// Возвращаемое значение:
//  Класс - Pet
//

или такие

// Описание функции (хттп метода)
//
// Параметры:
//  Нет
//
// Возвращаемое значение:
//  Структура
//         * Id Строка - Идентификатор блаблабла
//

EvilBeaver commented 5 years ago

я за второй вариант, ибо 1С-совместимо и не будет вызывать вопросов.

nixel2007 commented 5 years ago

А как же возврат представлений/результатов? Да ещё и динамический иногда: если все хорошо, то вьюха, а иначе 500?

nixel2007 commented 5 years ago

А так первое прям попахивает entity :)

dvakor commented 5 years ago

@nixel2007

Сваггер же больше про документацию АПИ, а какие там вьюхи. Хотя видел как-то, что из апи возвращался хтмл, правда 1 раз. Если рассмотреть данную ситуацию с точки зрения типов данных, то вьюха это хтмл, а хтмл это строка, собственно

//Блаблабла
// Возвращаемое значение:
//      Строка - представление чего-то там

Кстати в документации сваггера возвращаемый тип "файл" тоже имеет тип строка с форматом binary или byte. Да и у сваггера есть ограничение на типы данных, их не так много, только основные https://swagger.io/docs/specification/data-models/data-types/

Возврат кодов состояний можно сделать так:

//Блаблабла
// Возвращаемое значение:
//  Структура
//         * Id Строка - Идентификатор блаблабла
//     Код состояния
//         * 404 - Элемент не найден
//         * 400 - Не верные чего-то там

dvakor commented 5 years ago

@nixel2007

А так первое прям попахивает entity :)

Сначала подумал про entity framework, а потом вспомнил, что мне на инфостарте Лустин или Сосновый говорил про твой ОРМ, это ты его и имел ввиду как я понял))

Вообще может не с того места зашел, вместо внедрения в код самого проекта, можно было бы сделать возможность добавлять "плагины" для движка, которые бы имели доступ в ConfigureServices \ Configure, а там уже делай что хочешь, тогда можно бы было сделать все тоже самое, что я и щас сделал, но вынести логику генерации в оскрипт, а тут мы уже имеем https://github.com/bia-tech/autodocgen и твой entity. Соответсвенно сама логика генерации была бы в оскрипте, где больше свободы для конечного разработчика, ну и результат бы отдавался в провайдер сваггера. И поствлять в виде либы.

@EvilBeaver что думаешь?

nixel2007 commented 5 years ago

@ArchLord42RU я понимаю про swagger. я скорее про то, что oscript.web - это не только голые http-сервисы, возвращающие данные (то бишь бэкэнд). это еще и фреймворк для построения приложений. первый пример - odminus, который веб-обертка над rac.

nixel2007 commented 5 years ago

Сначала подумал про entity framework, а потом вспомнил, что мне на инфостарте Лустин или Сосновый говорил про твой ОРМ, это ты его и имел ввиду как я понял))

да, его) просто аннотации с типами над переменными класса - это прям оно :)

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

dvakor commented 5 years ago

@ArchLord42RU я понимаю про swagger. я скорее про то, что oscript.web - это не только голые http-сервисы, возвращающие данные. это еще и фреймворк для построения приложений. первый пример - odminus, который веб-обертка над rac.

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

EvilBeaver commented 5 years ago

@ArchLord42RU я могу тебе просто дать права на пуш в этот проект и ты будешь не пулреквестить, а напрямую пилить в движок?

Тут явно много экспериментирования потребуется, поэтому открытие/обсуждение реквестов, кажется преждевременным. Такое удобно, когда уже есть видение по той или иной теме. Здесь его нет и удобнее просто кодить и смотреть что получается, не?

dvakor commented 5 years ago

@EvilBeaver давай, создам ветку буду там экспереминтировать.

nixel2007 commented 5 years ago

Можно просто эту же ветку запушить в другой ремоут

dvakor commented 5 years ago

@nixel2007 ну можно и так, тут щас главное заиметь время на эксперименты) Я вот уже месяц прикручиваю ОСкрипт к Астериску через ARI, собственно буквально вчера добился более менее внятного синтаксиса со стороны ОСкрипта, при этом я не в свободное время делаю а в рабочее, т.к. проект для нужд компании.

EvilBeaver commented 5 years ago

Можно просто эту же ветку запушить в другой ремоут

Чо-чо сделать?

dvakor commented 5 years ago

@EvilBeaver я думаю он имеет ввиду текущую ветку закинуть в основной репо и с ней продолжить работать.

nixel2007 commented 5 years ago

Именно.

⁣Отправлено с помощью BlueMail

На 26 нояб. 2018 г., 0:52, в 0:52, Dmitriy Korolev notifications@github.com написал:п>@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

nixel2007 commented 5 years ago

Вам чиз одним писом или наслайсить? (с)

⁣Отправлено с помощью BlueMail

На 26 нояб. 2018 г., 0:16, в 0:16, Andrei Ovsiankin notifications@github.com написал:п>> Можно просто эту же ветку запушить в другой ремоут

Чо-чо сделать?

-- 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

dvakor commented 5 years ago

@EvilBeaver оп, я только что занотайсил, что экстеншены уже сделаны лонг тайм эгоу :) это который ExtensionsCompiler, только что-то не пойму не доделано оно? Кроме как в тесте работу с данным классом нигде не вижу.

EvilBeaver commented 5 years ago

Да, компилятор не доделан, т.к. эти API не работают в netstandard2.0

EvilBeaver / OneScript.Web

WIP: Поддержка генератора документации #48

47