| title | keywords | last_updated | sidebar | permalink | image | description |
|---|---|---|---|---|---|---|
Курс по документированию REST API |
документирование API, technical writers, технический писатель, курс документирования |
Oct 8, 2019 |
mydoc_sidebar |
index.html |
images/seo_image.png |
Курс по документированию API. Вольный перевод курса https://idratherbewriting.comlearnapidoc/ |
Курс по документированию API. Вольный перевод курса Documenting APIs: a guide for technical writers, составленного Томом Джонсоном, техническим писателем Amazon.
Тяжелых и скучных лекций об абстрактных понятиях здесь не будет.
Курс по написанию документации REST API подразумевает практический подход к документированию REST API. На этом курсе будем заниматься изучением документации API на примерах использования API сервисов прогноза погоды.
Разберем API на составные части, узнаем о конечных точках, параметрах, типах данных, аутентификации, curl, JSON, командной строке, консоли разработчика Chrome, JavaScript и прочих деталях, связанных с REST API.
Идея курса в следующем: посмотреть на реальные сценарии использования API, сделав этот курс эффективным. Изучать концепты API независимо от контекста мы не будем.
Во время прохождения курса:
- изучим стандарты, инструменты и спецификации REST API;
- узнаем о необходимых разделах в документации API;
- проанализируем примеры документации REST API различных компаний;
- узнаем, как присоединиться к опен-сорс проекту, для получения опыта;
- и многое другое.
-
О модуле "Используем 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
- Описание ошибок