🔄 Документирование API или что такое Swagger/OpenAPI

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

🔄 Лучшей практикой документации является спецификация OpenAPI - универсальный способ описания API в YAML или JSON-формате, который может использоваться с любым языком программирования. Раньше спецификация называлась Swagger и только при появлении версии 3.0 стала называться OpenAPI и стала open-source проектом.

🔥 Когда нужно быстро написать документацию, можно использовать библиотеку генерации спецификации OpenAPI, поддерживаемую вашим фреймворком, например, drf-spectacular для Django Rest Framework. Такие библиотеки позволяют сгенерировать файл с описанием API автоматически на основе исходного кода, однако описание и параметры для каждого эндпоинта разработчику нужно будет прописывать вручную.

Если у вас нет доступа к коду, можно написать spec-файл вручную в Swagger Editor, где есть онлайн-проверка корректности синтаксиса и отображение готовой документации через Swagger UI.

Готовый spec-файл можно загрузить в Swagger UI, который отобразит документацию в удобном виде.

☕️ Расскажите в комментариях, документируете ли вы API?

🎄 Поздравляем с Новым годом, наши дорогие Python-разработчики! Желаем в новом году новых полезных знаний и навыков!

👩‍💻 Совсем скоро мы порадуем вас новым курсом, где узнаёте всё о файлах и научитесь правильно работать с ними в своих проектах.

🦍 Когда мы создавали курс Python для pre-junior backend-разработчика, думали, что логичным его продолжением будет Python для junior backend-разработчика. После релиза первой части и начала работы над новым курсом, я обнаружил, что количество важных тем стремительно растет, а исключать их нельзя. Причем, самое забавное - начали разрастаться темы не про функции и ООП, а про всё, что вокруг них.

Именно в этот момент мы придумали курс 6 факторов Python-разработчика.

Откуда такое название?
Есть очень популярный гайдлайн The Twelve-Factor App, содержащий практики для разработки web-приложений. Мне всегда казалось, что было бы классно, если бы был курс, покрывающий каждый фактор этого гайдлайна. Именно таким и задуман курс шести факторов.

Он состоит из тем:
1) Работа в команде, где поговорим о контроле версий, код ревью, стиле кода и прочих мелочах, которые делают работу в команде слаженной.
2) Мониторинг проектов – научим обрабатывать исключения, логгировать и журналировать приложения, собирать метрики, работать с Sentry и Grafana.
3) Работа с файлами – уже готов! Вы узнаете как управлять кодировками, проведете нормализацию текста и напишете свой валидатор, подробнее в содержании курса.
4) Сеть и интернет – подробно разберем что такое HTTP, REST, GraphQL, TCP/IP и прочие вещи, связанные с интернетом.
5) Архитектура проекта – обсудим структуру проекта, пакетные менеджеры pip и Poetry, конфигурирование проекта с помощью .env, hydra и vault.
6) Продакшен – вы научитесь тестировать, собирать и деплоить свой код с помощью Docker и Kubernetes, а также настраивать CI/CD.

Темы получились обширными, поэтому 6 факторов стали циклом курсов. Мы хотим, чтобы наши курсы были гибкими, и вы могли сами выбирать интересные темы. Если кто-то знает все о файлах, но ему нужно разобраться с работой в команде, зачем ему покупать все 6 факторов, верно?

Первый фактор о файлах уже доступен для прохождения:

⚡️ Курс Работа с файлами в Python доступен для прохождения!
В честь его открытия мы сделали для вас промокод с 50% скидкой: FILEGURU. Он будет действовать до 1-го февраля.

Обязательно пройдите наш промо урок по текстовым файлам!