Комментарии 13
Да и стороннему заказчику такое не отдашь, все равно приходится писать текстовое описание.
>Да и стороннему заказчику такое не отдашь, все равно приходится писать текстовое описание.
У нас свагер используется в SAAS проекте, поэтому отдавать заказчику ничего не надо. А кроме того там хранится только документация для разработчиков. Для пользовательской используются совсем другие средства и даже другая команда.
бывают сложные сценарии, когда нужно дергать последовательность ручек, вот отсюда из ответа надо взять ИД и передать сюда итд.
В таком случае всё сведётся либо к добавлению упрощённого метода, либо к написанию текста к описанию этих сложных посладовательных методов с подсказками и примерами, ровно так же, как это нужно делать и в классической документации, разве нет?
Отличным местом для описания общения подходит Wiki, проверено. У этого способа описания API тоже есть свои недостатки. Основной, отсутствие генерации кода, зато можно описать что угодно.
1. Уродливая система объявления. Куча обязательных параметров, навроде description и прочего, без которого не заводится скрипт, какая то «местозависимая» система объявления (обязательные параметры не выходило менять местами — на кой черт они тогда именованные?) — но черт, мне нужно всего лишь отправить запрос
2. Ужасный онлайн редактор и вывод трейсбеков. Нельзя ровно ни скопировать ни вставить, ни потом запустить. Приходилось одно и тоже по 5 раз переписывать, понять где ошибка просто невозможно, табы/пробелы не различает не заменяет, короче боль. О автодополнении молчу.
3. Глючный UI JS. Создаем роут, описываем ответы, делаем запрос, если JS вдруг получит не то что ожидал (ну например у вас сервак что-то там запарился) — все, UI умирает, ничего отправить/принять нельзя. В хроме UI не работал СОВСЕМ.
4. Авторизация — да чуваки, в 2016 все пользовались только basic типом, и все, другого не дано. Ни совместную не сделать, ни отличную от того что предлагает сам «швагер», а скажите, как мне передать API ключ для всех запросов остальных? а ни как, сначала запускаешь первый запрос, получаешь ключ, и потом его руками копируешь. А что делать если api_key временный?
5. Генерация. Это совсем отдельная песня, такое чувство что он не знает о существовании каких то правил в языках, по крайней мере в питоне, Пустые роуты я и сам могу написать.
Большего терпеть я не стал, и прекратил работу с данным сервисом. У меня все. Не знаю как сейчас у них дела, но все описанное было правдой на лето 2016 года.
Lubos Palisek
Я не могу сказать, что Swagger идеален, но мне интересно что же стало его заменой в Вашем случае?
Для моих задач Swagger справляется на 4+. Давайте пройдёмся по вашим пунктам:
- "Уродливая система объявления" — похоже, что все описанные раздражающие вещи уже исправлены. Честно говоря, 40-50 методов руками генерировать и потом поддерживать — это сурово, я вот не знаю как автор поддерживает Swagger описания отдельно от своего кода. Я пришёл к тому, что сервер должен строить swagger.json на основании кода, на эту тему у меня есть демо-сервер — https://github.com/frol/flask-restplus-server-example
- Я не могу сказать, что я ежедневно использовал онлайн редактор, но ни разу он не вылетел у меня за последний год.
- Наверно, тоже исправлено, так как я ежедневно пользуюсь Swagger-UI — полёт нормальный, в том числе в Хроме.
- Базовая поддержка OAuth2 в Swagger-UI была добавлена осенью, а около месяца назад наконец добавили и OAuth2 Password Flow
- Что значит "пустые роуты"? Сейчас Python генерация вполне себе сносная (я даже недавно сделал её ещё более "Pythonic", но релиза не было с лета, это да… я мастер ветку использую — полёт нормальный)
Итого, единственный актуальный "камень в огород" Swagger — это практически отсутствующая поддержка различных способов авторизации (в Swagger-UI они наконец хоть что-то полезное добавили, но в кодогенерациях даже с поддержкой OAuth2 тухло, так что приходится патчить, но я надеюсь найти немного времени и прикрутить поддержку OAuth2 для Python и JS, которыми я активно пользуюсь и сейчас у меня накладываются не самые изящные патчи)
RESTful сервис можно сделать самодокументируемым. HATEOAS
Lubos Palisek
На мой взгляд, HATEOAS — это ужас ужасный. Из Swagger конфигурации можно получить статический клиент, и после этого взаимодействие сводится к обмену полезными данными, в то время как HATEOAS всё время будет слать кучу информации "на всякий случай". Чтобы был хоть какой-то выигрыш HATEOAS, клиент должен быть динамическим, принимающим какие-то решения в процессе взаимодействия, а если клиент декларативный, то пользы, по-моему, никакой. Мне нравится вот это описание: "А нужен ли мне HATEOAS?"
Я делаю второй проект АПИ на Swagger и некоторые моменты меня тоже раздражают. Но Wiki как способ документирования даже не рассматриваю. Blueprint? Какие ещё реально используемые технологичные альтернативы?
Насчёт самодокументирования это правильно. Сделать можно. Но сначала надо написать документацию на самодокументируемый сервис.
Документирование #микросервисов