Не сажайте разработчиков

И так полстраны по тюрьмам

расцвели орешники
разыграли тендеры
полстраны фпшники
полстраны фронтендеры

а я совмещаю

Девопсов забыл

Девопсы не люди

Сверхлюди?

Методологии

хорошо, назовем девопсЕРы

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

там все еще по инвайтам аудиторию набирают? 😆🙈

Не понял мотивации.....

дево-псы

Челики, а поделитесь, как вы оформляете доку для сервисного api. Вот у меня сейчас тапир для сваггера и встаёт вопрос о необходимости описания методов и параметров. Возможно о примерах. И вижу пока 3 варианта.

1 - прямо в коде вставлять краткое описание. Но тогда это сильно ухудшает читабельность роутеров.

2 - выносить в отдельный конфиг, подгружать через pureconfig и в коде только ссылаться на поля классов. Минус в том, что всякий бойлерплейт появляется.

3 - описывать отдельно в каком-нибудь конфлюенсе. Можно делать норм описание с форматированием. Но тогда смысл сваггера, возможно, несколько теряется.

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

Выносить в .properties бандлы и автоматически цеплять тупедсхемой

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

  summary("Add or update subscriptions")
  description(
    """<p>Add or update an array of subscriptions.</p>
    """)
  pathParam[String]("domain", "Customer we are subscribing", MinMaxLength(4, 128), Pattern(DOMAIN_CHARACTERS))
  pathParam[String]("recipientId", "Customer Recipient we are subscribing", MinMaxLength(1, 128), Pattern(FIELD_CHARACTERS))
  consumes[List[SubscriptionTO]]("application/json")
  tags("Recipient")
  post("/v1/customers/{domain}/recipients/{recipientId}/subscriptions", (domain: String, recipientId: String) => {

4. если есть необходимость i18n для доков, Олеговский вариант норм - по ендпоинту формируем ключ, затем в бандлах пишем текст по каждому полю

о, и заодно - никакой проблемы синхронизации нет.

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

Вот скажем, если с примерами описание строк на 20. То уже штук 10 таких в коде видеть не хотелось бы

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