API Документация за которую не стыдно

Сегодня мы поговорим о том как сделать документацию которую действительно кто то прочитает приятно читать.

Key Takeaways

1. API - это продукт
2. Если ваш API построен на REST - OpenAPI это мастхэв
3. Документацию по API можно скомпилировать и представить в виде статического HTML-файла. Этот подход может быть полезен для "Private" API.
4. Redocly

Документация API должна быть

1. Четкой и краткой: Сосредоточьтесь на практических примерах, которые пользователи могут быстро понять и применить.
2. Developer-Centric: Основные потребители вашей документации — это разработчики.
3. Интерактивной: Интерактивные инструменты позволяют разработчикам эффективно исследовать и понимать поведение API на самом раннем этапе.
4. Всегда актуальной: Ну или, по крайней мере, стремиться к этому 🙂

Документация — это самостоятельный продукт

Относитесь к документации API не только как к вспомогательному инструменту, но и как к важной части вашего продукта.

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

Типы API

На сегодня наиболее распространены два типа API:

• REST
• GraphQL

Примеры REST и GraphQL API

Рассмотрим один из примеров — это API GitHub, который предоставляет как REST, так и GraphQL интерфейсы.

Пример запроса в GraphQL

Запрос:

Ответ:

Пример запроса в REST

Запрос:

Ответ:

Как документировать API?

Так как REST API наиболее популярен сегодня, в основном благодаря своей простоте и широкой поддержке, сосредоточимся на нём.

OpenAPI

Некоторые компании все еще используют Word-документы (спасибо, что не PowerPoint) для описания API, что может привести к несогласованности, сложности в поддержании актуальной информации и отсутствию стандартизации.

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

Первоначально известная как Swagger Specification, OpenAPI предоставляет структурированный метод для описания всех конечных точек, параметров запросов, форматов ответов и методов аутентификации для API.

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

Что, если бы мы могли описать все конечные ендпоинты, параметры и примеры еще до их разработки? Это значительно сократило бы время разработки и минимизировало ошибки интеграции, делая весь процесс более эффективным.

Именно для этого и предназначен OpenAPI.

Пример "PetStore" можно найти здесь. Этот JSON-документ описывает, как работают API "petstore".

Преимущества и цели OpenAPI

• Стандартизация: OpenAPI предоставляет общий формат для описания API
• Автоматизация: Разработчики могут автоматизировать задачи, такие как генерация клиентских SDK, создание интерактивной документации и тестирование.
• Простота интеграции: Сторонние разработчики могут быстро понять, как интегрироваться с сервисом даже до его окончательной разработки/внедрения.
• Интерактивная документация: Инструменты, такие как Swagger UI/PostMan, позволяют пользователям тестировать endpoint'ы в пару кликов.
• Single Source of Truth

TL;DR

Спецификация OpenAPI включает доступные API ендпоинты, структуры данных, server-urls, настройки аутентификации, описания и диаграммы (используя Markdown/Mermaid).

Swagger

SwaggerUI — это инструмент для визуализации и взаимодействия с файлами OpenAPI, доступный здесь.

По умолчанию вы должны увидеть тот самый PetStore (из ссылки выше), благодаря Swagger документация в человеко-читаемом виде была автоматически сгенирирована лишь на основе OpenAPI документа.

В Swagger Editor вы можете:

• Авторизоваться через OAuth2
• Просматривать структуру API и конечные точки
• Отправлять запросы с кнопками "Try it"
• Редактировать схему API

Обычно используется подход "документация как код" с использованием спецификаций OpenAPI.

Documentation as Code — это подход к созданию и управлению документацией, который использует те же принципы и инструменты, что и в разработке программного обеспечения.

Окей, у нас есть OpenAPI файл, теперь давайте превратим его в более красивый вариант, чем предоставляет Swagger.

Redocly

https://github.com/Redocly/redoc

Redocly предлагает альтернативу Swagger, позволяя генерировать единую HTML-страницу, которую легко поделиться.

Пример тех же API "PetStore" через Redocly: Redocly Demo

Другие примеры:

• TRIP.com
• DigitalOcean

Как создать документацию в этом формате?

Цель — сгенерировать документацию PetStore локально и иметь один HTML-файл для распространения.

Установка Redocly:

npm i -g @redocly/cli@latest

Создайте папку для документации:

mkdir example
cd example

Скачайте OpenAPI Пример PetStore:

curl -O https://petstore3.swagger.io/api/v3/openapi.json

Просмотр документации локально:

redocly preview-docs openapi.json

Перейдите по адресу: http://127.0.0.1:8080, чтобы увидеть сгенерированную документацию. Любые изменения в файле будут автоматически обновлять документацию.

Сгенерируйте статичный HTML-файл:

redocly build-docs openapi.json

Откройте статичный HTML-файл:

open redoc-static.html

Поздравляем! Теперь у вас есть сгенерированный HTML-файл, которым вы можете легко поделиться.