Курс по документированию REST API

Вольный перевод курса 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 открытым исходным кодом, чтобы получить опыт, и многое другое.

Начать обучение 👨‍💻

Модули курса

1. Введение в REST API

   • Обзор курса
   • Видео презентации
   • Слайды курса
   • Практические занятия
   • Для чего этот курс
   • Об авторе
   • Рынок документации REST API
   • Что такое REST API
   • Практика: Определение цели

2. Использование API в роли разработчика

   • Сценарий использования API погоды
   • Получение ключей авторизации
   • Отправка запросов в Postman
   • Введение и установка curl
   • Создание curl запроса
   • Понимание curl
   • Использование методов с curl
   • Анализ JSON ответов
   • Изучение полезных данных JSON ответа
   • Доступ и вывод на страницу определенного значения JSON
   • Погружение в точечную нотацию

3. Документирование конечных точек

   • Документирование новой конечной точки
   • Обзор пошагового описания API ссылки
   • Шаг 1: Описание ресурса
   • Шаг 2: Конечные точки и методы
   • Шаг 3: Параметры
   • Шаг 4: Пример запроса
   • Шаг 5: Пример и схема ответа
   • Собираем все вместе
   • Практическое занятие: Что не так в разделе API?
   • Практическое занятие: Поиск open-source проекта
   • Практическое занятие: Оценка ключевых элементов API документации

4. Спецификация 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 с документацией

5. Тестирование документации

   • Обзор тестирования документации
   • Настройка тестовой среды окружения
   • Самостоятельное тестирование всех инструкций
   • Тестирование предположений
   • Практическое занятие: Тестирование документации проекта

6. Концептуальные разделы

   • Разделы руководства пользователя
   • Обзор API
   • Руководство по началу работы
   • Требования аутентификации и авторизации
   • Коды статусов и ошибок
   • Ограничения скорости
   • Описание и образцы кода
   • SDK и пример приложений
   • Краткое справочное руководство
   • API Глоссарий
   • Лучшие практики API
   • Практическое занятие: Оценка концептуального контента в проекте

7. Публикация документации

   • Обзор вариантов публикации документации
   • Список из 100 сайтов с API документацией
   • Шаблоны проектирования сайтов API документации
   • Инструменты Docs-as-code
   • Подробнее о Markdown
   • Система контроля версий (пример Git)
   • Практическое занятие: Управляем контентом в Wiki Github
   • Практическое занятие: Используем клиент GitHub для десктопа
   • Практическое занятие: процесс Pull request на GitHub
   • Генераторы статичных сайтов
   • Варианты хостинга и развертывания
   • Возможности автономных CMS
   • Рекомендации - какой инструмент документирования выбирать
   • Непрерывное развертывание Jekyll и CloudCannon
   • Кейс для изучения: Переход на Docs-as-code

8. Работа технического писателя

   • Рынок труда технического писателя
   • Необходимое количество кода, которое нужно знать
   • Лучшие локации для работы

9. Нативные библиотеки API

   • Обзор нативных библиотек API
   • Получаем пример Java проекта
   • Java Ускоренный курс
   • Практическое занятие: Генерация Javadoc из примера проекта
   • Теги Javadoc
   • Изучение вывода Javadoc
   • Редактирование тегов Javadoc
   • Doxygen, генератор документации для С++
   • Создание концептуальной документации при помощи исходных библиотек API

10. Глоссарий API и источники

    • Глоссарий API документации
    • Практические занятия REST API
    • Практическое занятие: Получить информацию о событии, используя API сервиса Eventbrite
    • Практическое занятие: Извлечь галерею, используя API сервиса Flikr
    • Практическое занятие: Получить скорость ветра, используя API сервиса Aeris Weather
    • Справочник RAML
    • Справочник API Blueprint
    • Описание ошибок

11. Документирование кода

    • Почему документирование кода так сложно?
    • Исследования о документировании кода
    • Пять стратегий документирования кода

Go next ➡