Вольный перевод курса Documenting APIs: A guide for technical writers, составленного Томом Джонсоном, техническим писателем Amazon.
Цель перевода курса:
- пройти курс, научиться документировать API, повысить свои soft skills техписателя;
- освежить знания английского языка;
Данный репозиторий используется для хранения исходников перевода.
Сайт русскоязычной версии курса: Starkovden.github.io
Курс по написанию документации REST API предполагает практический подход к документированию REST API вместо лекций об абстрактных понятиях. На этом курсе займемся изучением документации API на примерах использования API сервисов прогноза погоды.
Разбирая API, мы узнаем о конечных точках, параметрах, типах данных, аутентификации, curl, JSON, командной строке, консоли разработчика Chrome, JavaScript и других деталях, связанных с REST API.
Идея курса в следующем: посмотреть на реальные сценарии использования API, вместо изучения концептов API независимо от контекста, что сделает этот курс намного эффективнее.
Во время прохождения курса мы изучим стандарты, инструменты и спецификации REST API. Узнаем о необходимых разделах в документации API, проанализируем примеры документации REST API различных компаний, узнаем, как присоединиться к проекту c открытым исходным кодом, чтобы получить опыт, и многое другое.
-
Использование API в роли разработчика
- Сценарий использования API погоды
- Получение ключей авторизации
- Отправка запросов в Postman
- Введение и установка curl
- Создание curl запроса
- Понимание curl
- Использование методов с curl
- Анализ JSON ответов
- Изучение полезных данных JSON ответа
- Доступ и вывод на страницу определенного значения JSON
- Погружение в точечную нотацию
-
Документирование конечных точек
- Документирование новой конечной точки
- Обзор пошагового описания API ссылки
- Шаг 1: Описание ресурса
- Шаг 2: Конечные точки и методы
- Шаг 3: Параметры
- Шаг 4: Пример запроса
- Шаг 5: Пример и схема ответа
- Собираем все вместе
- Практическое занятие: Что не так в разделе API?
- Практическое занятие: Поиск open-source проекта
- Практическое занятие: Оценка ключевых элементов API документации
-
Спецификация OpenAPI и Swagger
- Обзор форматов спецификаций REST API
- Знакомство со спецификациями OpenAPI и Swagger
- Работа в YAML
- Обзор руководства OpenAPI
- Шаг 1: Объект
openapi - Шаг 2: Объект
info - Шаг3: Объект
servers - Шаг 4: Объект
paths - Шаг 5: Объект
components - Шаг 6: Объект
security - Шаг 7: Объект
tags - Шаг 8: Объект
externalDocs - Практическое занятие: Создание спецификации OpenAPI
- Руководство Swagger UI
- Демо Swagger UI
- Введение и руководство SwaggerHub
- Stoplight - инструмент визуального моделирования для создания спецификаций
- Интеграция Swagger с документацией
-
- Разделы руководства пользователя
- Обзор API
- Руководство по началу работы
- Требования аутентификации и авторизации
- Коды статусов и ошибок
- Ограничения скорости
- Описание и образцы кода
- SDK и пример приложений
- Краткое справочное руководство
- API Глоссарий
- Лучшие практики API
- Практическое занятие: Оценка концептуального контента в проекте
-
- Обзор вариантов публикации документации
- Список из 100 сайтов с API документацией
- Шаблоны проектирования сайтов API документации
- Инструменты Docs-as-code
- Подробнее о Markdown
- Система контроля версий (пример Git)
- Практическое занятие: Управляем контентом в Wiki Github
- Практическое занятие: Используем клиент GitHub для десктопа
- Практическое занятие: процесс Pull request на GitHub
- Генераторы статичных сайтов
- Варианты хостинга и развертывания
- Возможности автономных CMS
- Рекомендации - какой инструмент документирования выбирать
- Непрерывное развертывание Jekyll и CloudCannon
- Кейс для изучения: Переход на Docs-as-code
-
- Обзор нативных библиотек API
- Получаем пример Java проекта
- Java Ускоренный курс
- Практическое занятие: Генерация Javadoc из примера проекта
- Теги Javadoc
- Изучение вывода Javadoc
- Редактирование тегов Javadoc
- Doxygen, генератор документации для С++
- Создание концептуальной документации при помощи исходных библиотек API
-
- Глоссарий API документации
- Практические занятия REST API
- Практическое занятие: Получить информацию о событии, используя API сервиса Eventbrite
- Практическое занятие: Извлечь галерею, используя API сервиса Flikr
- Практическое занятие: Получить скорость ветра, используя API сервиса Aeris Weather
- Справочник RAML
- Справочник API Blueprint
- Описание ошибок