powered by simpleCommunicator - 2.0.27     © 2024 Programmizd 02
Map
Форумы / WCF, Web Services, Remoting [игнор отключен] [закрыт для гостей] / Web API. Как открыть интерфейсы?
51 сообщений из 51, показаны все 3 страниц
Web API. Как открыть интерфейсы?
    #39992384
Фотография Renziglov
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Привет.
Как клиент узнает какие интерфейсы доступны у Web API? В WCF для этого есть специальный MEF-endpoint. Там создается прокси на клиенте и все нтерфейсы клиенту сразу же становятся известны.
В какой-нибудь Web API REST нет никаких прокси. Как задисковерить чего этот зйпиай экспонирует?
Спасибо.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #39992448
Фотография skyANA
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Renziglov,

на данный момент есть OpenAPI спецификация, изначально известная как Swagger, для описания и взаимодействия с API
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #39992623
Фотография Renziglov
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
skyANA,

Я вполне подозреваю, что что-то есть. Но если это что-то просто заставляет разработчика API составлять некий документ, а получателя читать этот документ, чтоб получить список интерфейсов, то мои подозрения оправдываются. Если вы работали с этим, можете сказать как именно открываются интерфейсы? КоротЕнько, вот как я сказал про MEX и mexHttpBinding в случае с WCF.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #39992662
Дмитрий Мух
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Renziglov
Я вполне подозреваю, что что-то есть. Но если это что-то просто заставляет разработчика API составлять некий документ

Нет, моглы бы и потратить пять минут на чтение хотя бы Википедии.

OpenAPI (Swagger) - это целый набор инструментов, позволяющий как сгенерировать документацию по вашему коду, так и библиотеку-клиента к вашему API.
Эта библиотека оформляется как NuGet-пакет, и кому надо, тот ставит себе и пользуется.

А вот пример сгенерированной API-документации для разработчика: https://petstore.swagger.io/
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #39992665
Фотография Renziglov
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Дмитрий Мух,

Именно в Википедии и потратил. А вам спасибо за линк, он все прояснил. Т.е. создается документация и пользователь ее читает. Умно.
На одной из микрософтовских конференций мне была выдана маечка с таким принтом:

.NOT .NET
ASP.NET Forms Blazor
WCF gRPC
JavaScript C# 8.0

Надо смелее осваивать gRPC, товарищи!
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #39992681
Сон Веры Павловны
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Renziglov
Надо смелее осваивать gRPC, товарищи!

Зачем?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #39992802
vb_sub
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Сон Веры Павловны,
быстро, маленький размер сообщения, контракт на обращение к эндпоинту- все за что любят WCF.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #39992900
Дмитрий Мух
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Renziglov
Именно в Википедии и потратил.

И до второго параграфа даже не дочитали что-ли?

ЦитируюOpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами).
Если спроектирована спецификация для некоторого сервиса, то на её основании можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др .
Для этих действий имеется большой набор инструментов для различных языков программирования и платформИ ссылки на Getting Started и Tools and Integrations.

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

А может конечно и документацию читать и писать код ручками.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40013922
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
vb_sub
за что любят WCF.

За угрёбищный SOAP?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014104
Сон Веры Павловны
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
За угрёбищный SOAP?

Ээ.. а что, при работе с WCF кто-то работает непосредственно с SOAP? Мне доводилось сталкиваться со случаями, когда аппликухи на джаве при работе с веб-сервисами костылили SOAP-разметку, но в дотнете, где это всё хозяйство глубоко под капотом??
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014131
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Дмитрий Мух
А может конечно и документацию читать и писать код ручками.

Ну, когда из какого-нибудь развесистого API нужно всего пару методов, то, может быть, проще и руками написать :))
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014137
Фотография skyANA
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
Дмитрий Мух
А может конечно и документацию читать и писать код ручками.

Ну, когда из какого-нибудь развесистого API нужно всего пару методов, то, может быть, проще и руками написать :))

Написать что? Клиента, или вызов этих пары методов у готового клиента? :)
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014181
vb_sub
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
vb_sub
за что любят WCF.

За угрёбищный SOAP?

Можно его любить например за быстрый net tcp.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014491
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
skyANA
Клиента, или вызов этих пары методов у готового клиента? :)

Возможно я к вечеру туплю, но зачем писать или генерировать какие-то вызовы для готового клиента, если он уже готовый?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014503
Фотография skyANA
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
skyANA
Клиента, или вызов этих пары методов у готового клиента? :)

Возможно я к вечеру туплю, но зачем писать или генерировать какие-то вызовы для готового клиента, если он уже готовый?

Я не понял к чему ты написал "может быть, проще и руками написать". Проще, чем что?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014561
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
skyANA
Проще, чем что?

Чем настраивать конфигурацию кодогенерилки.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014643
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat,

А чё там её настраивать? OpenAPI это как бы есть конфиг, изначально на языке YAML, что как бы намекает :)
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014645
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat,

Некоторые идут дальше, пишут сначала спеку на OpenAPI, чтобы нагенерить как клиента, так и начальный код сервера :)
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014683
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
fkthat,

А чё там её настраивать? OpenAPI это как бы есть конфиг, изначально на языке YAML, что как бы намекает :)

Да это все понятно. На нашем проекте у меня вообще все в процесс билда встроено (NSwag) еще и дополнительным параметром "-p:blablabla" можно заставить его свежую копию OpenAPI Doc с сервера перед этим вытянуть. Но это наш собственный API, где под сотню методов, который нужен нам целиком, и который периодически обновляется.

Если же мне просто нужен какой-то один метод со стороннего сервиса, да и из него всего пару полей, то зачем мне все это шапито разворачивать, это как на самосвале за булкой хлеба в магазин поехать, быстрее руками какой-нибудь GET написать и забыть.

Да и какой там YAML, кстати? Там же JSON. Или ты о чем-то другом?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014684
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
Некоторые идут дальше, пишут сначала спеку на OpenAPI

Это как-то вообще бесчеловечно. Разве что, если какими-нибудь тулзами её рисовать. До сих пор с содроганием вспоминаю свой небольшой опыт разработки FE под ExtJS, в которой кода считай что вообще нет, потому что почти все приложение это куча каких-то километровых абсолютно наркоманских конфигов.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014685
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
Да это все понятно. На нашем проекте у меня вообще все в процесс билда встроено (NSwag)


Немного оффтопа, но мы от NSwag даже не просто ушли, а убежали со всех ног, ибо косяк на косяке, полный игнор в коммьюнити, не решаемые годами проблемы.

fkthat
Если же мне просто нужен какой-то один метод со стороннего сервиса, да и из него всего пару полей, то зачем мне все это шапито разворачивать, это как на самосвале за булкой хлеба в магазин поехать, быстрее руками какой-нибудь GET написать и забыть.


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

fkthat
Да и какой там YAML, кстати? Там же JSON. Или ты о чем-то другом?


Ну изначально Swagger на YAML-е основан, JSON-YAML обратно конвертируемы. Далее объясню зачем это всё.

fkthat
Это как-то вообще бесчеловечно. Разве что, если какими-нибудь тулзами её рисовать. До сих пор с содроганием вспоминаю свой небольшой опыт разработки FE под ExtJS, в которой кода считай что вообще нет, потому что почти все приложение это куча каких-то километровых абсолютно наркоманских конфигов.


Ну вот как раз YAML затем, чтобы писать спеку ручками.

Просто ты мыслишь исключительно из опыта 100% бекенд based API. Типа сначала пишем код сервиса, ток потом уже генерируем API спецификацию. А все остальные в то время курят бамбук, ждут когда же ты там разродишься своими спеками, ага :)

Если хотя бы на часок ты примеришь на себя роль постановщика, который должен спеку разрабатывать, прорабатывать и согласовывать, ты поймёшь, что писать в формате OpenAPI -- наверное лучшее, что на сегодняшний момент есть. При чём это универсально подойдёт для разных платформ, команд. Минимальными усилиями.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014716
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
Немного оффтопа, но мы от NSwag даже не просто ушли, а убежали со всех ног, ибо косяк на косяке, полный игнор в коммьюнити, не решаемые годами проблемы.

Да ладно там.

Swashbuckle: 3.5k stars, 863 forks, used by 5000+, 126 contributors
NSwag: 3.9k stars, 766 forks, used by 1330, 170 contributors

NSwag просто помоложе и он не просто OpenAPI, а еще и куча тулзов для той же кодогенерации в комплекте - из-за этого и был в свое время выбран.

hVostt
Просто ты мыслишь исключительно из опыта 100% бекенд based API. Типа сначала пишем код сервиса, ток потом уже генерируем API спецификацию. А все остальные в то время курят бамбук, ждут когда же ты там разродишься своими спеками, ага :)

Для меня, как для разработчика, код контроллера это такая же спека, как все то же самое описанное на yaml/json. История показывает, что все эти подходы "понарисуем квадратиков со стрелочками, а чудо-инструмент нам сам по ним код сгенерирует" это полный фейл. Лет десять назад резюме разработчика без упоминания UML это было вообще не резюме. Ну и где сейчас этот UML - впиши его в резюме и тебя засмеют :)) Единственное применение кодогенерации сервера что я сразу так вижу, это когда тебе надо реализовать какой-то чужой API точно в соответствие с чужой спецификацией (например web-hooks для стороннего сервиса)
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014725
Фотография Shocker.Pro
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
и всё же
В большой сервисной или микросервисной архитектуре, когда есть куча независимых команд, разрабатывающая кучу независимых сервисов, именно спецификация API будет точкой отсчета и будет разрабатываться раньше кода.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014875
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Shocker.Pro
и всё же
В большой сервисной или микросервисной архитектуре, когда есть куча независимых команд, разрабатывающая кучу независимых сервисов, именно спецификация API будет точкой отсчета и будет разрабатываться раньше кода.

Так необязательно сразу реализовывать. Напиши типы данных, которые actions принимают/отдают, пропиши роуты, и поставь везде всеми любимый
Код: c#
1.
throw new NotImplementedExceptions();


Я выше писал - интерфейс контроллеров и акций это ровно такая же спецификация API как и OpenAPI Doc, просто в другом формате, причем генерировать одно из другого можно и в ту и в другую сторону. Тут, наверное, просто вопрос, с чем команде удобней работать - описывать API на C# или на YAML/JSON. Точно так же как в древние времена COM - ты мог сначала написать кодом интерфейсы, а потом из них сгенерировать IDL/TypeLib, а мог наоборот - написать сначала IDL, а из него сгенерировать интерфейсы - и то и другое абсолютно равнозначно.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014940
Сон Веры Павловны
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
Тут, наверное, просто вопрос, с чем команде удобней работать - описывать API на C# или на YAML/JSON.

Или на XML. Доводилось мне сталкиваться с требованием, что перед созданием сервиса (WCF) сначала пишется его WSDL.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014994
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
Для меня, как для разработчика, код контроллера это такая же спека, как все то же самое описанное на yaml/json. История показывает, что все эти подходы "понарисуем квадратиков со стрелочками, а чудо-инструмент нам сам по ним код сгенерирует" это полный фейл. Лет десять назад резюме разработчика без упоминания UML это было вообще не резюме. Ну и где сейчас этот UML - впиши его в резюме и тебя засмеют :)) Единственное применение кодогенерации сервера что я сразу так вижу, это когда тебе надо реализовать какой-то чужой API точно в соответствие с чужой спецификацией (например web-hooks для стороннего сервиса)


Не, ты путаешь слегка. OpenAPI это весьма конкретная спецификация, которую можно быстро разрабатывать.

Квадратики это вообще маст хев, но в квадратики 90% людей не умеют, поэтому как пещерные аборигены, объясняют на пальцах, пишут код на основе туманных тезисов, которые каждый понимает по-своему. Отсутствие качественного анализа и постановки с "квадратиками" выливается в большое количество мусорной бесполезной коммуникации, дефектов и отладки.

Тебе нужно не только контроллер, но и модели + аннотации + комментарии + инварианты ответов с описаниями.

А потом если что не так? В спецификации OpenAPI нужно поправить несколько строк, а контроллерах всё переколбашивать.

Просто ты с таким не сталкивался, сам так работал и понимаю тебя прекрасно. Однако на основе более глубокого опыта, разработка спецификации до написания кода -- эффективнее на порядочек. При любых раскладах практически.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40014995
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
Я выше писал - интерфейс контроллеров и акций это ровно такая же спецификация API как и OpenAPI Doc, просто в другом формате, причем генерировать одно из другого можно и в ту и в другую сторону. Тут, наверное, просто вопрос, с чем команде удобней работать - описывать API на C# или на YAML/JSON. Точно так же как в древние времена COM - ты мог сначала написать кодом интерфейсы, а потом из них сгенерировать IDL/TypeLib, а мог наоборот - написать сначала IDL, а из него сгенерировать интерфейсы - и то и другое абсолютно равнозначно.


А теперь представь, тебе надо заинтегрироваться с другой командой. Тебе нужно, чтобы они тебе АПИ выставили, не один метод с парочкой полей, а несколько, допустим десяток со структурами разной сложности. Именно для тебя.

Ты к ним обращаешься, они согласны. Говорят, присылай спеку, мы реализуем.

Контроллер будешь колотить на коленке?
Ну вот это колхоз.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015016
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
Говорят, присылай спеку, мы реализуем.

Ну если так, тогда да. Я ведь раньше еще тут писал, что сценарий со спекой как раз хорошо подходит для реализации чужого API.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015021
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
hVostt
Говорят, присылай спеку, мы реализуем.

Ну если так, тогда да. Я ведь раньше еще тут писал, что сценарий со спекой как раз хорошо подходит для реализации чужого API.


Не обязательно. Давай тебе кейс.

Есть команда бек, есть команда фронт. Проект один.
Ты пилишь свои задачи, фронт свои.
Завтра спринт заканчивается, и надо начать пилить новые задачи.
По твоей методике, получается, фронт должен сидеть ждать пока ты свои контроллеры напишешь? :)
А если вдруг что-то на фронте не зайдёт, они не заценят твою сгенерированную спеку, будут замечания, код переписывать?

Как бы вовсе не чужое API, а твоё. Но спека нужна раньше, чем начнётся реализация. Да она может и поменяться в процессе, подкорректироваться, но необходимо максимально снизить подобные ситуации.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015027
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
По твоей методике, получается, фронт должен сидеть ждать пока ты свои контроллеры напишешь? :)

А зачем писать контроллеры? Я же опять-таки выше уже писал - достаточно написать только интерфейсы контроллеров. Написал интерфейсы - кинул им ссылку на /swagger и пускай себе пилят, а ты пили уже реализацию своих контроллеров.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015030
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
Квадратики это вообще маст хев, но в квадратики 90% людей не умеют, поэтому как пещерные аборигены

ЛОЛ, так это именно пещерные аборигены общались тем, что жирафов да бегемотов на стене рисовали, а развитые люди чтобы общаться как раз и придумали алфавит и письменность
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015037
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
hVostt
По твоей методике, получается, фронт должен сидеть ждать пока ты свои контроллеры напишешь? :)

А зачем писать контроллеры? Я же опять-таки выше уже писал - достаточно написать только интерфейсы контроллеров. Написал интерфейсы - кинул им ссылку на /swagger и пускай себе пилят, а ты пили уже реализацию своих контроллеров.


Так по сути контроллеры и есть интерфейсы, не?
:)

90% кода контроллеров -- интерфейс. Это модели данных, аннотации, комментарии, инварианты ответов, маршруты, политики, полный фарш.

fkthat
ЛОЛ, так это именно пещерные аборигены общались тем, что жирафов да бегемотов на стене рисовали, а развитые люди чтобы общаться как раз и придумали алфавит и письменность


Так развитые не по одним лекалам. Поэтому нужны наглядные изображения бизнес-процессов, те самые "квадратики", согласованный словарь и куча всего, чтобы коммуникация была эффективной.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015041
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
Это модели данных, аннотации, комментарии, инварианты ответов, маршруты, политики, полный фарш.

Ну так все это по любому придется и в JSON писать. Тот же фарш только в другом виде.

hVostt
Так по сути контроллеры и есть интерфейсы, не?

Код: c#
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
// вот это "интерфейс"
[HttpPost("accounts")]
[ProducesResponseType(StatusCodes.Status201Created)]
public Task CreateAccount(AccountModel model) => throw new NotImplementedException();

// а вот это реализация
[HttpPost("accounts")]
[ProducesResponseType(StatusCodes.Status201Created)]
public async Task CreateAccount(AccountModel model)
{
    await _accountService.CreateAccountAsync(_mapper.Map<AccountDto>(model));
    return Created();
}
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015051
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat,

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

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

а теперь в твоём сваггере вносят комментарии/изменения, как обратно "фарш" затолкаешь?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015111
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
ну так тебе надо написать код, скомпилить, запустить, открыть страничку со сваггером, вытащить файл, отдать.

А если все это делать в обратном порядке (от JSON к коду контроллера), то количество шагов сильно меняется?

И, вот как это выглядит в C#:
Код: c#
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
public record WeatherModel(DateTimeOffset Date, int TemperatureC, string? Summary);

[ApiController]
[Route("api/weather")]
public class WeatherController : ControllerBase
{
    [HttpGet("")]
    public IEnumerable<WeatherModel> GetWeather() =>
         throw new NotImplementedException();
}



А вот, как то же самое выглядит в OpenAPI (слабонервным спойлер лучше не открывать )

Код: javascript
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
{
  "x-generator": "NSwag v13.8.2.0 (NJsonSchema v10.2.1.0 (Newtonsoft.Json v9.0.0.0))",
  "openapi": "3.0.0",
  "info": {
    "title": "WeatherApi",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:7403"
    }
  ],
  "paths": {
    "/api/weather": {
      "get": {
        "tags": [
          "Weather"
        ],
        "operationId": "Weather_GetWeather",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WeatherModel"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WeatherModel": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "temperatureC": {
            "type": "integer",
            "format": "int32"
          },
          "summary": {
            "type": "string",
            "nullable": true
          }
        }
      }
    }
  }
}


...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015116
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt,

А еще, кстати, когда ты будешь писать свой мультикилометровый JSON, то тебе придется регулярно генерить из него код, чтобы проверить что он вообще генерится и что генерится то, что ты ожидаешь. А когда я буду писать свой C#, то у меня студия сама сразу будет мои косяки подсвечивать :))
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015361
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
А если все это делать в обратном порядке (от JSON к коду контроллера), то количество шагов сильно меняется?


На этапе разработки и согласования API меняется конечно.
Более того, если для тебя это станет привычным, ты только выигрываешь во всех отношениях.


fkthat
А вот, как то же самое выглядит в OpenAPI (слабонервным спойлер лучше не открывать )


Прекрасно выглядит. Но только не в JSON:

Код: python
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
x-generator: NSwag v13.8.2.0 (NJsonSchema v10.2.1.0 (Newtonsoft.Json v9.0.0.0))
openapi: 3.0.0
info:
  title: WeatherApi
  version: 1.0.0
servers:
  - url: 'https://localhost:7403'
paths:
  /api/weather:
    get:
      tags:
        - Weather
      operationId: Weather_GetWeather
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WeatherModel'
components:
  schemas:
    WeatherModel:
      type: object
      additionalProperties: false
      properties:
        date:
          type: string
          format: date-time
        temperatureC:
          type: integer
          format: int32
        summary:
          type: string
          nullable: true




fkthat
А еще, кстати, когда ты будешь писать свой мультикилометровый JSON, то тебе придется регулярно генерить из него код, чтобы проверить что он вообще генерится и что генерится то, что ты ожидаешь. А когда я буду писать свой C#, то у меня студия сама сразу будет мои косяки подсвечивать :))


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

Т.е. я внесу изменения, и все увидят понятные изменения, все потребители АПИ.
Более того, в её разработке могут участвовать все: бек, фронт, аналитики, потребители.

А когда ты внесёшь изменения в контроллеры и модели, кто поймёт какие конкретно изменения отразятся на АПИ? Никто. Кроме тебя.

Просто ты АПИ полностью лочишь на себе. Индивидуально с твоей точки зрения -- это конечно хорошо. Теперь все пляшут и танцуют вокруг тебя :)

Но с командной точки зрения и в целом для разработки проектов -- это крайне хреновый подход.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015362
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat,

Я в общем, рекомендую попробовать.

Возьми, например, вот это: https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi

Ты получишь вменяемый редактор спеки с интеллисенсом, валидацией и всей остальной фигнёй.
Ни чем абсолютно не отличается от написания кода на C# :)
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015370
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt
fkthat,

Я в общем, рекомендую попробовать.

Возьми, например, вот это: https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi

Ты получишь вменяемый редактор спеки с интеллисенсом, валидацией и всей остальной фигнёй.
Ни чем абсолютно не отличается от написания кода на C# :)

Посмотрю. Да только у меня тут новый проект, где у людей вообще только POST, и, (внимание!), всегда возвращается только 200, а если какая-то ошибка, то она передается в body неким магическим кодом. Когда я спросил, что это за ХЕРНЯ, то меня "успокоили", тем, что все эти коды ошибок у них в конфлюенсе задокументированы. Вот так вот. А ты мне тут про OpenAPI.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015371
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
Посмотрю. Да только у меня тут новый проект, где у людей вообще только POST, и, (внимание!), всегда возвращается только 200, а если какая-то ошибка, то она передается в body неким магическим кодом. Когда я спросил, что это за ХЕРНЯ, то меня "успокоили", тем, что все эти коды ошибок у них в конфлюенсе задокументированы. Вот так вот. А ты мне тут про OpenAPI.


Эээ, я с таким уже сталкивался :)
Забирали проект от внешнего подрядчика, а там типа того, POST, иногда GET и все ответы только 200.
На мой вопрос, это чё за херня, мне ответили, это JRPC...
Прастите што?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015441
monstrU
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt,

помнишь, на сайте как то была бурная дискуссия про то как ответы в web api оформлять -
вариант 1 - коды ответов 200, 400 500 использовать и давать тело ответа
вариант2 - код ответа 200 для успешного ответа и 500 для ошибок
в ваших проектах вы что используете ?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015444
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
monstrU
hVostt,

помнишь, на сайте как то была бурная дискуссия про то как ответы в web api оформлять -
вариант 1 - коды ответов 200, 400 500 использовать и давать тело ответа
вариант2 - код ответа 200 для успешного ответа и 500 для ошибок
в ваших проектах вы что используете ?

Меня, вот еще интересует. Надо ли по best practice перечислять "очевидные" статусы - 401, 403, 500, или это лишнее.

200 надо указывать явно, потому что успешный ответ это не всегда 200, а может быть и любой другой двухсотый, те же, например, 201, 202, 204.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015503
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
monstrU
hVostt,

помнишь, на сайте как то была бурная дискуссия про то как ответы в web api оформлять -
вариант 1 - коды ответов 200, 400 500 использовать и давать тело ответа
вариант2 - код ответа 200 для успешного ответа и 500 для ошибок
в ваших проектах вы что используете ?

Не все ошибки это 500. 500 это значит "неизвестный песец на сервере". Поэтому возвращать всегда 500 это полнейший говнодизайн.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015681
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat
Меня, вот еще интересует. Надо ли по best practice перечислять "очевидные" статусы - 401, 403, 500, или это лишнее.


Совершенно лишнее.

Вот здесь много чего интересного: https://swagger.io/docs/specification/describing-responses/
Смотри разделы "Default Response" и "Reusing Responses".

fkthat
Не все ошибки это 500. 500 это значит "неизвестный песец на сервере". Поэтому возвращать всегда 500 это полнейший говнодизайн.


Можно считать, что 500 означает, что требуется чинить.
"Рядовых" 500 быть не должно.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40015684
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
monstrU
помнишь, на сайте как то была бурная дискуссия про то как ответы в web api оформлять -
вариант 1 - коды ответов 200, 400 500 использовать и давать тело ответа
вариант2 - код ответа 200 для успешного ответа и 500 для ошибок
в ваших проектах вы что используете ?


вариант 1, кодов ответов больше.

надо понимать, что код ответа нужен не для удовлетворения внутреннего перфекциониста.
а для вполне конкретных задач. для организации единого мониторинга и построения понятного API.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40016220
monstrU
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
hVostt,

я по архитектуре веб сервисов дальше рассуждаю - рассматриваю какой вариант.
возьмем абстрактный пример получение по номеру паспорта ФИО и даты рождения человека.
то есть имеем сервис
/passport/person?passportNumber=41001234
и по нему возвращаем ответ 200 и тело запроса
Код: javascript
1.
2.
3.
4.
5.
6.
7.
{
 'Response':{
               'FIO':'Путин Вова',
               'BirthDaty':'19600201'
             },
 Explanations:[]
}


на запрос
/passport/person?passportNumber=4100123
возвращаем ответ 400 и тело
Код: javascript
1.
2.
3.
4.
{
   'Response':null,
   Explanations:['в номере паспорта должно быть 8 символов']
}


то есть подход какой - веб сервис возвращает не объект, а ответ на запрос.
а он уже состоит из ответа, когда он есть, или из объяснения причины отказа в ответе - отказ запроса по бизнес требованиям.
как то у меня такой подход сложился - у вас как ?
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40016225
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
monstrU

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

Да, вполне очеь даже нормальный подход. Только я бы возвращал завернутое в массив, потому что по REST URI типа /passport/person это коллекция и возвращать следует коллекцию. Если бы URI были типа /passport/person/41001234 то тогда либо 200 + объект, либо 404. Я придерживаюсь такого, что все что до "?" это URI ресурса, а все что после "?" это некие параметры представления этого ресурса (например, фильтрация, сортировка, пейджинг и т.п.). Что-то плохое до вопроса - это 404 (ресурса нет), а все что плохое после вопроса - это 400 - ресурс есть, но запрос к нему кривой.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40016276
Фотография hVostt
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
monstrU
то есть подход какой - веб сервис возвращает не объект, а ответ на запрос.
а он уже состоит из ответа, когда он есть, или из объяснения причины отказа в ответе - отказ запроса по бизнес требованиям.
как то у меня такой подход сложился - у вас как ?


Если сложился, то хорошо.

Но лично на мой взгляд плохо.
Благодаря коду ответа (например, 200/400) мы имеем возможность легально возвращать разные типы данных. Соответственно, педалить один и тот же тип со значимыми полями, которые могут содержать null в случае ошибки -- хреново.

Т.е. содержать структуру, которая содержит Payload, (в вашем случае 'Response'), это прям убер костыль. Масло маслянное, HTTP уже даёт мощные инструменты для реализации чистого АПИ.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40016724
monstrU
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
fkthat,
обращу внимание - возвращается ответ веб сервиса, поэтому объект с ответом один.
в моем примере веб сервис возвращал только одну персону, поэтому объект с ответом был

'Response':{
'FIO':'Путин Вова',
'BirthDaty':'19600201'
},
если бы веб сервис был такой, что возвращает несколько персон, то само собой нужно было написать

'Response':[{
'FIO':'Путин Вова',
'BirthDaty':'19600201'
}]

hVostt,
объясню откуда выполз 'Response':null,
для подключения к веб-сервисам сделали агента на серверной стороне, который как раз возвращает CS объект с ответом веб сервиса. Физическое подключение было сделано библиотекой, которая сама ответ сериализовывала в cs объект (RestSharp был использован)

В случае невалидных параметров при коде 400 архитектура потребовала
1. выдать массив с разъяснением причин отказа проверки
2. и для успешной сериализации ответа поставить 'Response':null, так как Response заполняется в случае успешного ответа 200

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

{
'Response':null,
Explanations:['в номере паспорта должно быть 8 символов']
}
Да и архитектурно получается вроде логичное объяснение: при отказе при валидации нет ответа веб сервиса и есть разъяснение причин отказа

fkthat, hVostt
вообще мнение по вопросу опять поделилось - один голос сказал за, второй голос против.
кстати в прошлом топике про веб апи так же было.
так что видимо на уровне предпочтений.
мой пример вылез из того, что реально загрузкой занимается библиотека с автоматический сериализацией ответа
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40016727
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
monstrU
fkthat,
обращу внимание - возвращается ответ веб сервиса, поэтому объект с ответом один.
в моем примере веб сервис возвращал только одну персону, поэтому объект с ответом был

'Response':{
'FIO':'Путин Вова',
'BirthDaty':'19600201'
},
если бы веб сервис был такой, что возвращает несколько персон, то само собой нужно было написать

'Response':[{
'FIO':'Путин Вова',
'BirthDaty':'19600201'
}]

Да можно и так, в общем-то, в REST что и плохо, что нет по сути никаких стандартов. Просто, допустим, мы решили доработать наш API поддержкой запроса /passport/person/?firstName=Вова и тогда он уже будет возвращать:
Код: javascript
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
'Response':[
  {
    'FIO':'Путин Вова',
    'BirthDaty':'19600201'
  },
  {
    'FIO':'Пупкин Вова',
    'BirthDaty':'19730908'
  }
]


Получится не очень удобно. Все-таки, на мой вкус, запрос к коллекции должен возвращать коллекцию.
...
Рейтинг: 0 / 0
Web API. Как открыть интерфейсы?
    #40016739
fkthat
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
monstrU

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

{
'Response':null,
Explanations:['в номере паспорта должно быть 8 символов']
}

https://tools.ietf.org/html/rfc7807 This document defines a "problem detail" as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

Поэтому не нужно ничего своего выдумывать.
...
Рейтинг: 0 / 0
51 сообщений из 51, показаны все 3 страниц
Форумы / WCF, Web Services, Remoting [игнор отключен] [закрыт для гостей] / Web API. Как открыть интерфейсы?
Целевая тема:
Создать новую тему:
Автор:
Закрыть
Цитировать
Найденые пользователи ...
Разблокировать пользователей ...
Читали тему (0):
Читали форум (0):
Пользователи онлайн (0):
x
x
Закрыть


Просмотр
0 / 0
Close
Debug Console [Select Text]