Какие существуют лучшие практики для описания документации для Websocket?

Question

[Станислав]

Ситуация: есть потребность создать новый эндпоинт в существующем сервисе, который до этого работал только синхронно по HTTP. Новый эндпоинт будет:

• принимать соединения от фронта;
  
• получать от фронта потоково аудио;
  
• передавать под капотом данные аудио в сервис расшифровки текста по gRPC;
  
• потоково (чанками) возвращать текст;
  
• как-то штатно или с той или иной ошибкой закрывать соединение.
  

Что хочется получить от документации:

• некий стандарт без костылей;
  
• описание процесса подключения и серверов, портов;
  
• версионируемость эндпоинта (как это делается для вебсокетов?);
  
• описание потокового ввода и вывода чанками;
  
• описание кодов ошибок, успешных кодов.
  

Остановиться хотелось бы либо на OpenAPI, либо на AsyncAPI, так как они всем понятны. Но если стандартом является другие варианты, готов рассмотреть и их.

Какие смущают вопросы, как имеющего опыт в написании документации в формате OpenAPI / AsyncAPI:

• Как версионировать?
  
• Как корректно описывать поток?
  
• Есть ли разделение например на установку соединения и описание что происходит внутри него?
  
• В какую сторону смотреть при выборе пути эндпоинта, можно ли применять к ним те же правила, что привычны для REST / RPC или иных вариантов?
  

Comments

[VoidVolker]

Станислав ручку? Дверную? Таки давайте может всё-таки будем придерживаться общепринятой терминологии? А то это уже будет нарушением правил.

[Станислав]

VoidVolker, без проблем, просто неоднократно слышу именно такое название в разных местах. Какой термин здесь следует использовать на ваш взгляд?

[historydev]

Станислав, конечная точка, маршрут - меньше фломастеров англицизма слушать нужно.

[Станислав]

historydev, как насчет метод приложения?

[historydev]

Станислав, зачем выдумывать бурду, если это давно сделали за вас?

[Станислав]

historydev, извините, не готов рассуждать о бурде. До свидания.

[historydev]

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

[VoidVolker]

Станислав, стандартный термин — end-point, конечная точка, точка подключения, маршрут.

извините, не готов рассуждать о бурде. До свидания.

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

[Александр Ме]

VoidVolker, всё правильно - эндпоинт. Но я тоже не понял что за ручка)

[Станислав]

Александр Ме, ребят, ну не слышали и не слышали, я вот слышал и не раз и не два, как и пяток других :-) Выбрал в итоге эндпоинт, среди вариантов, что ближе собравшимся тут. Всем спасибо!

[Станислав]

VoidVolker,

правил сервиса

Я и стараюсь их придерживаться, уточняя у сообщества, какие термины им ближе исходя из опыта.

Будьте любезны придерживаться правил приличия и ... за хамство вам никто отвечать не будет и вообще забанят.

Что касается правил приличия — ровно тот же ответ, стараюсь не поддерживать диалог, в котором переходят на оценки опыта других категориями "бурда".

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

[VoidVolker]

Станислав,

ребят, ну не слышали и не слышали, я вот слышал и не раз и не два, как и пяток других

Дело не в том, что слышали или не слышали, а в самом факте использования жаргонизмов. В правилах чётко указано, что они запрещены. Кроме того, жаргонизмы на то и жаргонизмы, как и всякие местячковые названия, который каждый второй выдумывает кучу, что где-то используются, где-то нет и не все с ними знакомы. Использование стандартных, понятных всем терминов упрощает коммуникацию и облегчает взаимопонимание. Согласитесь, ведь, намного приятнее читать и легче воспринимать текст, когда он написан понятным и простым языком, нежели в виде слабосвязанного потока слов и букв?

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

А вот это уже проявление неуважения к отвечающим на вопрос. Да, можно предложить правки вопроса. Спрашивающих всегда намного больше отвечающих. Как думаете, много ли будет отвечающих, если вот так каждый будет задавать вопрос как попало? Предлагаете редактировать каждый второй вопрос и приводить его в нормальный вид? А смысл? Если спрашивающий даже не потрудился потратить чуть большего своего времени и просто нормально по-человечески задать вопрос, то какой вообще смысл тратить время на такого? А вы полистайте список вопросов и посмотрите на вопросы без ответа: абсолютное большинство либо слабосвязанный поток слов либо игнорирование вопросов в комментариях. Вот, кстати, может сами их хотите подредактировать?
А ещё есть такая штука, как поиск: через поиск, если у кого-то возникнет похожа проблема и он используя стандартные термины легко найдёт вопрос и спокойно ознакомится с ответами. А ведь реально приходится один и тот же запрос в поиск вбивать с использованием различных синонимов несколько раз в надежде найти ответ на каком-нибудь другом форуме или сайте. Думаете удобно это? Не-а.

Спасибо еще раз за комментарии, хоть и не по существу.

А вот и не угадали. Комментарии очень даже по существу. Правила — штука довольно-таки существенная. Они не просто так, а для облегчения взаимодействия между пользователями сервиса.

Выбрал в итоге эндпоинт, среди вариантов

Отлично! Спасибо.

[Станислав]

VoidVolker,

В правилах чётко указано, что они запрещены.

Давайте прочитаем правила как они написаны, а не как вы их прочитали:

3. В процессе создания вопроса пользователь Сервиса обязан:

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

Обратите внимание на глагол (не) следует в разъяснении данного пункта правил. Обратимся к RFC 2119, который наверняка читали авторы правил данного сообщества, в его переводе на русский:

3. SHOULD - следует
Это слово, а также глагол рекомендуется (RECOMMENDED) используется для обозначения требований, от выполнения которых можно отказаться при наличии разумных причин. Однако при таком отказе следует помнить о возможных проблемах в результате отказа и принимать взвешенное решение.

Дальше можете додумать самостоятельно, умею ли я читать, писать, находить разумные причины тому, что я пишу, а также к кому я обращался, насколько узок или широк круг таких специалистов, насколько мой опыт и знания позволяют мне судить о том, что такое жаргонизм, а что англицизм, и тд и тп. А у меня рабочий день уже закончен, извините. Приятного вечера, ребята с сотней ачивок по всем темам Q&A :-)

PS: На остальное не вижу смысла отвечать, уже дал все комментарии выше.

Answer 1

[VoidVolker]

Ровно все те же самые, как и при описании любого другого API. Простота, удобство, читабельность, поддерживаемость. Можно спокойно использовать стандартный JSDoc или стандартную документацию вашего ЯП. Мне, например, нравится jsight.io за лёгкость и простоту. А вот сваггер и опен-апи — не нравятся, слишком переусложнено.

JSIGHT 0.3 

GET /cats/{id} 
  200 
    {
      "id"   : 123,   // {min: 0}
      "name" : "Tom"
    }

Comments

[Станислав]

К сожалению, не готов сейчас изучать совсем новые вещи, особенно если это не заточено именно под Websocket.

[historydev]

Станислав, Интересное умозаключение, так вам нужны лучшие практики или те что вы привыкли использовать?

[VoidVolker]

Станислав, повторюсь ещё раз: API для сокетов ничем принципиально не отличается от любого другого. Используйте стандартный JSDoc или стандартную документацию вашего ЯП, раз нет желания изучать что-то другое.

[Станислав]

повторюсь ещё раз: API для сокетов ничем принципиально не отличается от любого другого.

Я не знаю, почему и пришел с вопросом, есть ли что-то отдельное для Websocket, как есть отдельно например OpenAPI для HTTP API и AsyncAPI для событийных / асинхронных API.

Но спасибо за ответ, я понял вашу позицию.

[VoidVolker]

Станислав, OpenAPI / AsyncAPI тоже вполне отлично подходят и используются для веб-сокетов. Подойдёт вообще любой способ для описания API. Кстати, вот просто приведу пример документации к моей либе для веб-сокетов: https://github.com/VoidVolker/reqs - стандартный JSDoc в исходниках и подробное описание каждого метода в ридми.

[Станислав]

Спасибо за ссылку, посмотрю и подробнее отвечу уже завтра!