Обзор инструментов и услуг для документирования вашего веб -приложения Python от инструкций по установке до публичного API. Как убедиться, что документация по API синхронизирована с вашим кодом. Как обслуживать внутреннюю документацию и сохранить ее в частном порядке.
Почему документация имеет значение
Один из лучших вопросов, которые вы можете задать команде, прежде чем присоединиться к ней, – это ли она какая -либо документация. Что касается ресторанов, грязные ванные комнаты говорят на грязной кухне; Для компаний -разработчиков программного обеспечения плохая документация пахнет ржавым дизайном программного обеспечения и плохими процессами.
Ниже я поделюсь тем, что я знаю о инструментах для создания API и проектной документации. Я не буду касаться вопросов процессов; Это отдельная тема. Здесь только инструменты и услуги. Мой контекст по умолчанию для проекта – это веб -проект, разоблачающий HTTP API и, вероятно, написанный на Python.
Документация API
Независимо от того, если API является государственным или частным, его необходимо задокументировать. У нас есть несколько вариантов на тарелке.
Dropbox Paper или Google Docs. Самый простой подход – написать все документы вручную. В Doist для проектов API мы использовали документы Dropbox и поделились ими через команду. Преимущество этого подхода состоит в том, что вы можете первым API без какого-либо кода, быстро, итерация быстро, не нужно ничего устанавливать или преобразовать между форматами и можете быстро собрать обратную связь на месте.
С другой стороны, этот подход становится громоздким довольно быстро. В конечном итоге вы, лежащие вокруг нескольких документов, с различными форматами, и, кроме того, эти документы выходят из синхронизации с фактическим API довольно быстро. Несмотря на то, что я удобно, я бы не рекомендовал Dropbox Paper или Google Docs для чего -либо, кроме черновых версий API.
Драфт API в бумаге Dropbox
Сланец и друзья Анкет Следующим шагом к более контролируемой эволюции документации API является инструмент, подобный Slate и документация API в GIT. Это все еще текст, который вам нужно написать вручную на уценке, но Slate предоставляет структуру, гладкий рендеринг и позволяет вам публиковать свой API в качестве независимого веб -сайта.
Документация API Todoist сделана из Slate
Одна проблема с Slate заключается в том, что он объединяет код, пользовательский интерфейс и вашу документацию в одном хранилище. Их способ установки инструмента – клонирование всего репо и замена их образца контента на ваш. Нет простого способа обновить ваше приложение до новой версии API. Вы можете снова клонировать и скопировать свои файлы, если ваши единственные изменения будут только на стороне документации, но если вы обнаружили, что настраиваете пользовательский интерфейс, обновление становится более сложным.
Другая проблема, и, возможно, гораздо большая, заключается в том, что для поддержания документации и фактического API требуется значительные усилия и усердие. Если кто -то добавляет новое поле в объект, им нужно помнить, чтобы соответствующим образом обновить документацию. С помощью Slate вы не можете сделать больше, чем запоминание, но позже мы посмотрим, как мы можем решить эту проблему, генерируя документацию из кода.
Спецификация OpenAPI
Кого заботится о редакторах или уценке Wysiwyg, когда вы пишете Yaml! Все любят Yaml, и экосистема Openapi позволяет вам воспользоваться вашей страстью. Давайте поговорим больше о OpenAPI и о том, что он приносит на стол.
Все любят Yaml. Источник
OpenAPI в 2021 году следует рассматривать как стандартный de-facto для языка спецификации API. Причиной №1 придерживаться OpenAPI за пределами Pure Love к YAML, является инструмент, который позволяет писать, проверять, проверять, измерять, документировать свой API, отображать его веб -сайтом, генерировать спецификации API из кода и генерировать клиентов API из спецификаций Анкет
Редакторы OpenAPI
Есть два способа написать спецификации OpenAPI. Самый простой подход – написать спецификацию вручную. В сочетании с сервисами изделия OpenAPI, это также самый быстрый способ разблокировать ваших разработчиков на стороне клиента и позволить им работать с API, которого еще не существует.
Чтобы понять, как выглядит OpenAPI, вы можете начать с онлайн -редактора в editor.swagger.io Анкет
Онлайн редактор Swagger
Я бы не рекомендовал использовать онлайн -редактор для чего -то серьезного. К счастью, вы можете иметь такую же функциональность в своем IDE или редакторе с расширением.
Когда я нахожусь в VSCODE, я использую Редактор OpenAPI от 42Crunch Анкет
Редактор OpenAPI в VSCODE
В Pycharm я использую Openapi Спецификации плагин от Jetbrains. Плагин от 42Crunch также доступен, если вы предпочитаете.
Редактор Openapi от Jetbrains в Pycharm
OpenAPI рендереров
Рендеристы OpenAPI принимают вашу спецификацию YAML и превращают ее в веб -сайт с красиво отформатированной документацией.
Swagger UI это самый популярный рендерер. Он идет еще дальше, чем создание просмотра документации, и позволяет играть с вашим API прямо из браузера.
Swagger UI является чисто клиентской стороной. Он запускает код JavaScript, который считывает спецификацию из удаленного URL, анализирует его и преобразует его в интерфейс.
Если вы установили расширение IDE, вам не нужно ничего устанавливать. Все расширения поставляются с командой, открывающей пользовательский интерфейс Swagger прямо в окне редактора: это то, что вы только что видели на предыдущих скриншотах. Если вы хотите установить его, вы можете найти все различные варианты в их Инструкции по установке Анкет
Если у вас установлен Docker, самый простой способ начать работу с отдельным пользовательским интерфейсом Swagger – это запустить его с помощью одной команды:
docker run -p 8080:8080 swaggerapi/swagger-ui
Пользовательский интерфейс Swagger будет доступен в http://localhost: 8080 Анкет
Redoc , альтернатива Swagger UI. У него гладкий трехколонный интерфейс, похожий на Slate. API выглядит круто, но игровая площадка API предоставляется только в их оплачиваемой версии.
Redoc поддерживает дополнительные поля в ваши атрибуты, так называемые (расширения поставщиков) [ https://github.com/redocly/redoc#swagger-vendor-extensions ] Эти поля предоставляют больше вариантов для контроля того, как представить документацию. Например, вы можете добавить ключ X-Codesamples В соответствии с вашими характеристиками запроса и предоставьте образцы кода на разных языках программирования. Если вы хотите что -то похожее на Slate, но сгенерировано автоматически, это, вероятно, самое близкое, что вы можете получить.
Как и в случае с Swagger UI, Docker – самый быстрый способ запустить Redoc:
docker run -p 8080:80 redocly/redoc
Redoc будет доступен в http://localhost: 8080 Анкет
Redoc, обслуживающий файл из Localhost
Генерировать OpenAPI из кода
Некоторые фреймворки могут генерировать спецификации OpenAPI для вас. Вы можете перестать беспокоиться о дивергенции между вашей спецификацией и реализацией. Спецификация построена из кода, и она всегда актуальна!
FASTAPI это структура, которая приходит на ум в первую очередь. Он думает, живет и дышит OpenAPI и позволяет выразить Довольно продвинутые конструкции OpenAPI с питоном.
Django-rest-framework это структура, которая может сделать все для вашего API. При этом, когда я использую его, я обнаружил, что если вы не используете модели сериализаторы, то невозможно написать приличную спецификацию API из кода. В конце концов, я обнаружил, что написание простого файла YAML с нуля был быстрее и проще. Таким образом, вот Схема API Guide и вот Руководство о том, как представить документацию Анкет
Apispec это не фреймворк, а библиотека, которая обеспечивает питонический интерфейс для конструкций OpenAPI. Он имеет несколько интеграций с различными инструментами и рамками, включая колбу, пирамиду, AIOHTTP и Falcon. Список интеграций доступен на Экосистема страница.
Внутренняя документация
Что написать Анкет Хотя целевой аудиторией документации API является разработчики на стороне клиента, основной аудиторией внутренней документации являются разработчики самой услуги.
Там мы описываем такие вещи, как инструкции по установке и конфигурации, архитектурный выбор или руководящие принципы. Внутренняя документация может помочь ориентироваться в коде, развернуть вещи к производству, добавить новую зависимость, применить миграцию базы данных и т. Д.
Где хранить. Я предпочитаю хранить документацию по внутренней службе в том же хранилище, что и сама служба в отдельном каталоге, например док . Чем ближе документация к коду, тем меньше шансов вывести его из синхронизации с реализацией. Не задумывайтесь над этим. Что -то столь же простое, как куча файлов разметки в каталоге, может работать. Другие разработчики могут просматривать документацию прямо из своего редактора или использовать интерфейс GitHub.
Предоставление внутренней документации
Следующим шагом в оптимизации опыта с документацией является превращение этой документации в отдельный веб -сайт. Здесь любой статический генератор сайтов может помочь, но Python World предоставляет несколько «традиционных» вариантов, которые подходят для документации и интегрируются с другими инструментами и услугами.
SPHINX является стандартным де-факто в мире Python. Мощный, но немного на сложной стороне, чтобы освоить. С этим высказыванием большинство проектов с обширной документацией предпочитают сфинкс, а не альтернативы.
Mkdocs пытается сделать написание документации восхитительным процессом. В отличие от Sphinx, MKDOCS использует Markdown под капотом. Экосистема уценки богата и простирается далеко за рамки Python. Плагины, редакторы, форматер, преобразователи, все в вашем сервисе. Конфигурация MKDOCS проста. В самой простой форме это один файл YAML с именем проекта и список страниц.
# File mkdocs.yml site_name: My Project nav: - Home: index.md - About: about.md
Мой выбор для документации по проекту Python – MKDOCS с MKDOCS-Material тема.
Другие визуализаторы
Красота внутренней документации в том, что вы не ограничитесь специфическими рамками DOC; Вы можете использовать любой статический генератор сайтов. Многие из них имеют темы, специально подходящие для веб -сайтов документации. Я предоставляю ниже несколько примеров.
Пеликан , #1 статический генератор сайта, написанный на Python.
Хьюго это популярная рамка на базе Голанга для строительных площадок. Хьюго руководит этим блогом. Шаблоны документации Анкет
Docusaurus это статический генератор сайтов из Facebook. Их основная цель – помочь правильно и хорошо получить документацию, но они позволили создать любой веб -сайт, так как это приложение React.
Next.js делает еще один шаг дальше от лагеря с документацией/статическими генераторами сайтов. Это не совсем статический генератор сайтов, а скорее полностью отреченная платформа на основе React, которая способна экспортировать страницы в HTML . Если вы друг JavaScript и React, это может быть вариантом, но это избыточно в качестве отправной точки.
Обслуживание внутренней документации
Все, что может служить статическому веб -сайту, может служить вашей документации. Если вы не хотите публиковать свою документацию, выберите решение, которое может сделать вашу документацию частной. Ниже я предоставлю некоторые решения, которые вы должны соответствовать вашим потребностям.
Прочитайте документы является стандартным DE-FACTO для обслуживания технической документации, особенно популярной среди проектов с открытым исходным кодом. Он поддерживает Sphinx и Mkdocs из коробки, поддерживает несколько версий документации и локализованных версий. Проект readthedocs.com Обеспечивает коммерческую поддержку и обслуживает как государственную, так и частную документацию.
GitHub Pages Это естественный выбор, если вы сохраняете свои проекты и документацию на GitHub. Начиная с планов тарифов на профессионал или команды, Вы можете сделать свои страницы видимыми только для своих сотрудников Анкет
Гитлаб Страницы Предоставляет ту же функциональность, но в отличие от GitHub, частные веб -сайты доступны даже в бесплатной учетной записи. Есть группа Gitlab Страницы С примерами документации по обмену проектами, в том числе mkdocs , SPHINX , среди десятков других.
NetLify Хорошо интегрируется с рабочими процессами CI/CD и бесплатно для общественных сайтов. Pro Version позволяет создавать защищенные паролем сайты, а бизнес-план обеспечивает контроль доступа на основе ролей.
Во всех трех случаях вы создаете свою документацию в конвейере CI/CD и создаете статические страницы на сервере.
Мой стек
Чтобы завершить обсуждение документации, я поделюсь своими предпочтениями для стека.
- Формат спецификации API: OpenAPI.
- Редактор Spectapi: Pycharm.
- Чтобы сгенерировать API из кода: FASTAPI.
- Чтобы отобразить API: Swagger UI.
- Чтобы написать документацию: mkdocs.
- Чтобы обслуживать документацию: ничего (ничего (не читается из редактора) или прочитайте документы.
Если вам это нравится, пожалуйста, поделитесь этим и отметьте меня. Я @rdotpy . Если вы хотите обсудить это, напишите мне. Мой DMS открыт.
Оригинал: “https://dev.to/imankulov/21-tools-to-document-your-python-project-11l1”