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

dvakor · 2018-11-12T04:29:11Z

Пока я собрался сделать ПР.
@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 · 2018-11-13T07:44:12Z

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

EvilBeaver · 2018-11-19T19:57:29Z

src/OneScript/Infrastructure/SwaggerServicePlugin.cs

+                info.License = lic;
+            }
+
+            var contactSection = infoSection?.GetSection("Contact");


А что такое "Контакт" применительно к документации на API?

Это собственно контакт (выводится в шапке страницы), некая сущность с которой можно связаться, если у потребителя api возникнут вопросы.
Обычно там или контакты конкретного человека указывают или ИТ отдела.
Визуально выглядет так

Вообще вот тут можешь пощупать как это работает.
Там сразу по идее должен у тебя должно подтянутся демо описание проекта.
http://editor.swagger.io/

EvilBeaver · 2018-11-20T15:07:06Z

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

dvakor · 2018-11-20T19:41:05Z

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

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

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

Начнем с 1.

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

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

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

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

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

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

dvakor · 2018-11-20T19:46:49Z

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

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

или такие

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

EvilBeaver · 2018-11-20T20:37:13Z

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

nixel2007 · 2018-11-21T02:42:35Z

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

nixel2007 · 2018-11-21T02:43:08Z

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

dvakor · 2018-11-21T03:44:14Z

@nixel2007

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

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

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

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

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

dvakor · 2018-11-21T04:06:41Z

@nixel2007

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

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

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

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

nixel2007 · 2018-11-21T04:07:39Z

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

nixel2007 · 2018-11-21T04:09:17Z

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

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

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

dvakor · 2018-11-21T04:09:36Z

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

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

EvilBeaver · 2018-11-21T08:23:12Z

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

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

dvakor · 2018-11-24T07:00:44Z

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

nixel2007 · 2018-11-24T07:40:51Z

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

dvakor · 2018-11-24T10:22:09Z

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

EvilBeaver · 2018-11-25T17:16:55Z

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

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

dvakor · 2018-11-25T17:52:43Z

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

nixel2007 · 2018-11-26T02:02:06Z

Именно. ⁣Отправлено с помощью 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: #48 (comment)

nixel2007 · 2018-11-26T02:02:33Z

Вам чиз одним писом или наслайсить? (с) ⁣Отправлено с помощью 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: #48 (comment)

dvakor · 2018-11-26T05:48:53Z

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

EvilBeaver · 2018-11-26T17:16:34Z

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

dvakor added 2 commits November 12, 2018 10:47

Добавление сваггера в проект

2859f52

Добавление UI

e706537

EvilBeaver reviewed Nov 19, 2018

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

dvakor commented Nov 12, 2018

EvilBeaver commented Nov 13, 2018

EvilBeaver Nov 19, 2018

dvakor Nov 20, 2018

EvilBeaver commented Nov 20, 2018

dvakor commented Nov 20, 2018

dvakor commented Nov 20, 2018 •

edited

Loading

EvilBeaver commented Nov 20, 2018

nixel2007 commented Nov 21, 2018

nixel2007 commented Nov 21, 2018

dvakor commented Nov 21, 2018

dvakor commented Nov 21, 2018 •

edited

Loading

nixel2007 commented Nov 21, 2018 •

edited

Loading

nixel2007 commented Nov 21, 2018

dvakor commented Nov 21, 2018

EvilBeaver commented Nov 21, 2018

dvakor commented Nov 24, 2018

nixel2007 commented Nov 24, 2018

dvakor commented Nov 24, 2018 •

edited

Loading

EvilBeaver commented Nov 25, 2018

dvakor commented Nov 25, 2018

nixel2007 commented Nov 26, 2018 via email

nixel2007 commented Nov 26, 2018 via email

dvakor commented Nov 26, 2018

EvilBeaver commented Nov 26, 2018

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

Are you sure you want to change the base?

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

Conversation

dvakor commented Nov 12, 2018

EvilBeaver commented Nov 13, 2018

EvilBeaver Nov 19, 2018

Choose a reason for hiding this comment

dvakor Nov 20, 2018

Choose a reason for hiding this comment

EvilBeaver commented Nov 20, 2018

dvakor commented Nov 20, 2018

dvakor commented Nov 20, 2018 • edited Loading

EvilBeaver commented Nov 20, 2018

nixel2007 commented Nov 21, 2018

nixel2007 commented Nov 21, 2018

dvakor commented Nov 21, 2018

dvakor commented Nov 21, 2018 • edited Loading

nixel2007 commented Nov 21, 2018 • edited Loading

nixel2007 commented Nov 21, 2018

dvakor commented Nov 21, 2018

EvilBeaver commented Nov 21, 2018

dvakor commented Nov 24, 2018

nixel2007 commented Nov 24, 2018

dvakor commented Nov 24, 2018 • edited Loading

EvilBeaver commented Nov 25, 2018

dvakor commented Nov 25, 2018

nixel2007 commented Nov 26, 2018 via email

nixel2007 commented Nov 26, 2018 via email

dvakor commented Nov 26, 2018

EvilBeaver commented Nov 26, 2018

dvakor commented Nov 20, 2018 •

edited

Loading

dvakor commented Nov 21, 2018 •

edited

Loading

nixel2007 commented Nov 21, 2018 •

edited

Loading

dvakor commented Nov 24, 2018 •

edited

Loading