Создание документации по API
Документирование API репозитория исходного кода имеет важное значение для обеспечения ясности, специальных возможностей и простоты использования для разработчиков, поддерживающих и потребляющих API. Полная документация служит руководством для понимания функциональных возможностей, входных данных, выходных данных и использования конечных точек API. При документе API следует выбрать наиболее подходящий формат презентации (например, спецификацию OpenAPI или Markdown), включая примеры и сценарии использования, сохранить его up-to-date с изменениями кода и запрашивать отзывы от потребителей API для постоянного улучшения качества.
Хотя общий подход к документированием API не зависит от платформы, существуют некоторые различия в его реализации между Azure DevOps и GitHub.
Документирование API в Azure DevOps
Чтобы добавить документацию ПО API в проект Azure DevOps наиболее эффективно, следует использовать специальное средство документации или платформу, которая интегрируется с рабочим процессом разработки. Популярные варианты в этой категории включают Swagger (OpenAPI), схемы API и системы документации на основе Markdown, такие как MkDocs или Docusaurus. Их возможности интеграции Azure DevOps помогают автоматизировать процесс создания документации, сохраняя ее в синхронизации с базой кода. Большинство средств документации также поддерживают анализ встроенных комментариев и включая их в автоматически созданной документации.
Вы должны опубликовать документацию ПО API в центральном расположении, доступном членам команды и заинтересованным лицам. Это может быть выделенный веб-сайт документации, вики-сайт в Azure DevOps или внешний портал документации.
Кроме того, можно использовать заметки или декораторы кода непосредственно в коде для добавления метаданных, описывающих конечные точки API. Такие средства, как Swagger Codegen или Springfox, могут обрабатывать эти заметки и создавать файлы спецификаций OpenAPI.
Настройте автоматические процессы в Azure Pipelines для создания документации API всякий раз при изменении базы кода. Это гарантирует, что документация остается up-to-date и отражает последние изменения в API.
Документирование API в Github
При использовании GitHub рекомендуется создавать документацию по API, используя средства, которые являются частью экосистемы GitHub.
Начните с документирования конечных точек API, операций, параметров, ответов и других соответствующих сведений. Рассмотрите возможность создания этой документации в формате Markdown, чтобы обеспечить широкую поддержку и простоту использования. Определите согласованную структуру отдельных документов, разделив каждый из разделов, описывающих проверку подлинности, конечные точки, параметры запроса, примеры ответа и т. д.
Как и в Azure DevOps, можно использовать генераторы документации или генераторы статических сайтов для упрощения процесса создания документации ПО API из файлов Markdown. Популярные варианты включают Jekyll, MkDocs, Docusaurus и Hugo. Настройте генератор для анализа файлов Markdown и создания статических HTML-страниц. Вы можете настроить макет, тему и стили, чтобы соответствовать фирменной символике и предпочтениям проекта.
Чтобы опубликовать HTML-содержимое, используйте GitHub Pages, которые позволяют размещать статические веб-сайты непосредственно из репозитория GitHub. Для этого можно создать выделенную ветвь и отправить HTML-файлы в эту ветвь. Вы также можете реализовать GitHub Actions для автоматической сборки и развертывания документации ПО API при каждом изменении файлов документации или базы кода.
Настройте GitHub Actions для автоматической сборки и развертывания документации ПО API при изменении файлов документации или базы кода. Настройте рабочий процесс автоматизации, чтобы создать HTML-файлы документации с помощью выбранного генератора документации и развернуть их на GitHub Pages.