Практические занятия

В разделе собраны практические занятия всего курса.

Часть 1 Знакомство с API документацией

Практическое занятие "Идентификация целей"

👨‍💻 Определение цели документирования API

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

Ответьте на следующие вопросы:

Для чего вам этот курс?
Каковы ваши карьерные амбиции, связанные с документацией API?
Востребована ли работа технического писателя API документации?
Что вы считаете метрикой успеха для этого курса?
У вас есть техническое мышление, необходимое для достижения успеха в области документации для разработчиков?

Для живых семинаров мы обычно делимся ответами в формате, понятном каждому. Но если вы посещаете этот курс онлайн, подумайте о записях своих мыслей в журнале или записи блога.

Подробная информация для этого практического занятия находится по ссылке Обзор курса

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

Практическое занятие "Исследуем API OpenWeatherMap"

👨‍💻 Знакомство с API OpenWeatherMap

Изучим базовые разделы OpenWeatherMap API

Перейти на страницу https://openweathermap.org
Перейти в раздел API, кликнув по нему в навигационной панели
В секции Current weather data кликнуть на кнопку API Doc

Разобраться в информации, предоставленной в Current weather data API. Вызов API позволяют разработчикам запрашивать информацию для своих приложений. Другими словами, API предоставят данные для приложений, которые разрабатывают разработчики.

Ответить на вопросы о конечных точках API Current weather data :

Предоставляет ли API нужную информацию о температуре, скорости и направлении ветра, и текущих условиях (Подсказка: посмотрите на пример ответа API, кликнув по ссылке Example)?

Какими способами можно указать местоположение для информации о погоде?

Как выглядит пример запроса?

Сколько конечных точек имеет API?

Какие учетные данные нужны для получения ответа?

Подробная информация для этого практического занятия находится по ссылке Сценарий Использования API погоды

Практическое занятие "Получаем ключ авторизации OpenWeatherMap"

👨‍💻 Получаем ключ авторизации OpenWeatherMap

Перейти на страницу https://openweathermap.org
Нажать Sign Up в навигационной панели и создать аккаунт
После создания аккаунта вернуться на страницу https://openweathermap.org и кликнуть Sign in
После входа попадаем в панель разработчика. Кликнуть на плашку API key
Сохранить сгенерированный ключ в удобном месте.

Подробная информация для этого практического занятия находится по ссылке Получение ключа авторизации

Практическое занятие "Создаем запрос в Postman"

👨‍💻 Создаем запросы в Postman

Создаем Запрос

Использование инструмента Postman для создания запроса о текущих погодных данных при помощи конечной точки API OpenWeatherMap.

Если еще не установлен Postman, откройте сайт https://www.getpostman.com/ и установите приложение
Запустить приложение
Выбрать метод GET (обычно выбирается по умолчанию)
Вставить конечную точку https://api.openweathermap.org/data/2.5/weather в ячейку справа от метода
Открыть вкладку Params под методом и вписать следующие значения:

key: zip / value: 95050

key: units / value: imperial

key: appid / value: APIKEY

Вставить в значение ZIP и appid нужный индекс и ключ авторизации API

Интерфейс Postman будет выглядеть так:

При добавлении параметров они будут отображаются в виде строки запроса к URL-адресу конечной точки в поле GET.

Конечная точка примера будет выглядеть так: https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=8d3f4ca3fe57058a39b58b2a30945699 (но с другими значениями API ключа)

Параметры строки запроса отображаются после знака "?" и разделяются между собой амперсандом "&". Порядок параметров в строке запросов значения не имеет.

Многие API передают ключ API в заголовке, а не в качестве параметра строки запроса в URL-адресе запроса. (Если бы это было так, вы бы кликнули вкладку «Headers» и вставили необходимую пару ключ-значение в заголовок.)

Кликнуть на кнопку Send

Ответ появится в нижней панели. Пример:

Сохраняем запрос

В Postman нажать на кнопку Save (правее Send)
В диалоговом окне ввести имя запроса, например: "OpenWeatherMap Current API"
В описании запроса написать краткое описание запроса (опционально), например: "gets the current weather for 95050 in imperial units."
Проскроллить окно немного вниз и нажать Create collection для создания папки, куда будет сохранен запрос. После создания выбрать созданную папку.

После создания папки кнопка Save станет активной. Диалоговое окно будет выглядеть примерно так:

Нажать Save to (имя папки)

Сохраненные конечные точки будут видны в панели слева в Коллекциях. Если панель "Коллекции" не видна, нажать кнопку Show/Hide Sidebar в нижнем левом углу.

Создаем запрос на 5-дневный прогноз

Теперь вместо получения текущей погоды, используем другую конечную точку OpenWeatherMap для получения прогноза. Введите данные в Postman для 5-дневного прогноза. В Postman вы можете щелкнуть новую вкладку или щелкнуть стрелку рядом с «Сохранить» и выбрать «Сохранить как». Затем выберите свою коллекцию и запросите название.

Пример конечной точки для 5-дневного прогноза, который указывает местоположение по почтовому индексу, выглядит следующим образом:

https://api.openweathermap.org/data/2.5/forecast?zip=95050,us

Добавим в параметры запроса значения API и units

https://api.openweathermap.org/data/2.5/forecast?zip=95050&appid=APIKEY&units=imperial

В своей ссылке замените APIKEY на ключ API

Создаем еще один запрос OpenWeatherMap

Сделаем еще один запрос API OpenWeatherMap, на этот раз изменив параметры, которые использовали ранее для указания местоположения (для любой конечной точки). Например, если указали местоположение по почтовому индексу, изменим его на географические координаты lat и lon.

Например:

https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147

Подробная информация для этого практического занятия находится по ссылке Отправка запросов через Postman

Практическое занятие 2.4. Создаем запрос в curl

👨‍💻 Создаем запросы в curl

Открыть Postman
В любом запросе кликаем на кнопку Code под кнопкой Save
В диалоговом окне "Generate Code Snippets" выбираем cURL из выпадающего списка и нажимаем на кнопку Copy to Clipboard

Код Postman для запроса прогноза погоды OpenWeatherMap выглядит в формате cURL следующим образом:

curl -X GET \
      'https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147' \
      -H 'Postman-Token: dcf3c17f-ef3f-4711-85e1-c2d928e1ea1a' \
      -H 'cache-control: no-cache'

Postman добавил свою информацию о хедере (обозначено -Н) Тэги добавленного заголовка можно удалить. Также можно удалить знаки \, они добавлены для читаемости текста.

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

Вот запрос curl с удаленными символами -H и обратной косой чертой, а одинарные кавычки преобразованы в двойные кавычки:

curl -X GET "https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147"

Curl доступен на MacOS по умолчанию. Если на Windows curl еще не установлен, то инструкции по установке по ссылке, нужно выбрать одну из бесплатных версий с правами Администратора.
Открываем терминал

на OS Windows нажимаем ctrl+R и вводим команду cmd, Правой кнопкой мыши вызываем меню и выбираем Paste для вставки запроса.
на MacOS открываем iTerm или терминал, нажимая cmd+Пробел и вводим команду Terminal Вставляем запрос в командную строку и жмем кнопку Enter

Ответ от OpenWeatherMap на наш запрос будет выглядеть так:

{"coord":{"lon":-121.96,"lat":37.35},"weather":[{"id":801,"main":"Clouds","description":"few clouds","icon":"02d"}],"base":"stations","main":{"temp":65.59,"pressure":1014,"humidity":46,"temp_min":60.8,"temp_max":69.8},"visibility":16093,"wind":{"speed":4.7,"deg":270},"clouds":{"all":20},"dt":1522608960,"sys":{"type":1,"id":479,"message":0.1642,"country":"US","sunrise":1522590719,"sunset":1522636280},"id":420006397,"name":"Santa Clara","cod":200}

Этот запрос минимизирован. Вы можете развернуть его, например на сайте JSON pretty print или, на MacOS с установленным Python добавив | python -m json.tool в конец cURL запроса, чтобы минимизировать JSON в ответе.

Для подробностей можно посмотреть ветку Stack Overflow по этой теме.

Самостоятельно сделаем curl запрос на 5-дневный прогноз, сохраненный в Postman.

Подробная информация для этого практического занятия находится по ссылке Создание curl запроса.

Практическое занятие 2.5. Создаем AJAX-запрос и проверяем полезную нагрузку

👨‍💻 Создаем запрос на странице с помощью AJAX.

На этом занятии будем использовать JavaScript для отображения ответа API на веб-странице. Для создания запроса AJAX будем использовать автоматически сгенерированный код jQuery из Postman.

В текстовом редакторе (например, Sublime Text) создадим новый файл HTML (который содержит основные теги HTML) и вставим в него следующий скрипт:

<html>
<meta charset="UTF-8">
  <head>
      <title>Sample page</title>
      <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
  </head>
<body>
  <h2>Sample page</h2>

</body>
</html>

Сохраняем файл на ПК, с именем weather.html.
Открываем Postman и переходим к конечной точке, которую вы настроили в предыдущем действии (см. «Создаем запросы в Postman»).
Кликаем на кнопку Code и выбираем JavaScript > jQuery AJAX.

Код AJAX должен выглядеть так:

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial",
  "method": "GET",
  "headers": {
    "cache-control": "no-cache",
    "postman-token": "e9be9756-b922-89b3-7109-66bc4cf06b17"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Нажимаем кнопку Copy to Clipboard для копирования примера кода.
В том же шаблоне, который начали создавать на шаге 1, добавляем пару тегов <script></script> под ссылкой jQuery, а затем вставляем скопированный код Postman между тегов script.
В коде jQuery убираем объект headers, вставленный Postman

"headers": {
	"cache-control": "no-cache",
 	"postman-token": "e9be9756-b922-89b3-7109-66bc4cf06b17"
	}

Убираем запятую после "method": "GET".

Финальный код должен выглядеть так:

<!DOCTYPE html>
<html>
   <meta charset="UTF-8">
   <head>
      <meta charset="UTF-8">
      <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
      <title>Sample Page</title>
      <script>
         var settings = {
           "async": true,
           "crossDomain": true,
           "url": "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial",
           "method": "GET"
         }

         $.ajax(settings).done(function (response) {
           console.log(response);
         });
      </script>
   </head>
   <body>
      <h1>Sample Page</h1>
   </body>
</html>

Совет: Файл можно посмотреть по ссылке. (Добавлено несколько инструкций по открытию консоли разработчика, потому что в противном случае отображение страницы на этом этапе в учебнике было бы совершенно пустым.)

Запускаем Chrome и открываем JavaScript Console перейдя View > Developer > JavaScript Console..
В Chrome переходим в «Файл»> «Открыть файл» и выберите файл weather.html. (Если вы не видите меню «Файл» в Chrome, нажмите Cmd + O или Ctrl + O или просто перетащите файл weather.html в окно браузера.)

Тело страницы будет пустым, но ответ о погоде должен быть записан в консоли JavaScript (из-за кода console.log (response) в запросе). Если развернуть объект, возвращенный в консоль, он будет выглядеть следующим образом:

Теперь эта информация доступна для интеграции на вашей странице.

Подробная информация для этого практического занятия находится по ссылкам Изучение полезных данных JSON ответа и Доступ и печать определенного значения JSON

Часть 3 Документирование конечной точки API

Практическое занятие "Поиск опен-сорс проекта"

👨‍💻 Ищем опен-сорс проект с необходимостью документирования API

Для поиска нужного проекта:

Открываем расширенный поиск GitHub
Скроллим экран и ищем раздел Issues Options. В поле With the labels вписываем help wanted. Это стандартный тег, который команды используют для привлечения добровольцев в свой проект (но некоторые команды, которым нужна помощь, могут его и не использовать). Скроллим вверх и замечаем, что надпись: «Требуется помощь» автоматически заполняется в поле Advanced Search.
В поле Advanced Search добавляем ключевые слова documentation и api перед тегом help wanted

Нажимаем кнопку Search и видим результат

В полученном списке можно поискать проект REST API (а не API нативной библиотеки, такой как Java API). Есть ли проекты, которые выглядят интересными или перспективными? Если так, отлично. Если нет, добавляем ключевые слова и продолжаем искать.

Если поиск на GitHub не дал подходящих проектов, можно поискать на следующих ресурсах:

Trending GitHub projects
Crowdforge
Up for Grabs
Bus Factor
Code Triage
Changelog
24-hour Pull Requests
Programmableweb.com API directory

Примечание. Можно потратить много времени на поиск, оценку и участие в проекте с открытым исходным кодом. Для этого упражнения хорошо бы сосредоточиться на проекте, который выглядит только слегка интересным. Не обязательно сразу коммититься, это можно сделать в любое время.

После выбора проекта пометим следующее:

Задействован ли REST API в проекте?
Как в проекте помечены проблемы, связанные с документацией? Например, используется ли в нем ярлык «документация»?
Определяем текущее состояние документации проекта: является ли она надежной, скудной, обширной, есть она вообще?
Насколько активен проект? (Какова частота коммитов?)
Сколько участников в проекте?

Примечание: Вам еще пока не нужно связываться или взаимодействовать с командой. Вы просто собираете информацию и анализируете потребности в документации здесь.

Подробная информация для этого практического занятия находится по ссылке Поиск опен-сорс проекта

Практическое занятие "Оценка ключевых элементов API документации""

👨‍💻 Оценка ключевых элементов API документации

Практическое занятие позволит рассмотреть документацию API и определить общие элементы. Для оценки документации:

В списке 100 сайтов с API документацией или из полученного на предыдущем практическом занятии результата выбираем сайт или несколько сайтов с API документацией
На каждом сайте ищем секцию документации API ссылок (список конечных точек)
В документации по каждой ссылке находим информацию:

описание ресурса;
конечные точки и методы;
параметры;
примеры запроса;
примеры ответа и схемы.

Названия разделов могут отличаться на разных сайтах API-документации, но обычно они легко узнаваемы.

Оцените документацию API, ответив на следующие вопросы для каждого раздела:

Описание ресурса
- является ли описание action-oriented?
- краткое ли резюме (1-3 предложения)?
Конечные точки и методы
- как сгруппированы конечные точки (на одной или нескольких страницах? Сгруппированы по методу или по ресурсу)?
- как определены методы для каждой конечной точки?
Параметры
- сколько параметров у конечной точки (заголовок, путь, строка запроса, параметры тела запроса)?
- определены ли типы данных для каждого параметра (string, boolean, etc)? указаны мин/макс значения?
Примеры запроса
- в каком формате или на каком языке показан запрос (curl, специфичный язык или другое)?
- сколько параметров включает в себя пример запроса?
Примеры ответа
- представлены ли ответ и схема ответа? актуально ли описание каждого элемента?
как сайт документации обрабатывает вложенные иерархии в определениях ответов

Подробная информация для этого практического занятия находится по ссылке Оценка ключевых элементов API документации

Часть 4 OpenAPI и Swagger

Практическое занятие "Знакомство со Swagger при помощи Petstore Demo"

👨‍💻 Знакомство со Swagger при помощи Petstore Demo

Переходим по ссылке Swagger Pet Store Demo

Как и в большинстве основанных на Swagger'е инструментов, в интерфейсе Swagger есть кнопка «Try it out». Для работы необходима авторизация в Swagger. Авторизация по нажатии на кнопку Authorize, в появившемся окне нужно вставить корректную информацию. При желании авторизоваться можно добавив любой номер в поле api_key и нажав Authorize. Окно авторизации Petstore предназначено только для демонстрации, так что окно можно просто закрыть.

Окно авторизации в Swagger UI

Разверните конечную точку Pet
Нажимаем на кнопку Try it out. После нажатие пример значения в поле "Тело запроса" станет редактируемым.

Кнопка Try it out в Swagger UI

В примере заменяем значение id на другое целое (не повторяющееся) число. Далее меняем значение value на какое-нибудь узнаваемое (имя щенка - Puppy).
Нажимаем Execute

Выполнение примера Petstore запроса

Swagger UI отправляет запрос и показывает отправленный curl. В примере был отправлен curl:

curl -X POST "https://petstore.swagger.io/v2/pet" -H "accept: application/xml" -H "Content-Type: application/json" -d "{ \"id\": 1000, \"category\": { \"id\": 0, \"name\": \"string\" }, \"name\": \"Bentley\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"available\"}"

Обратите внимание, что с параметром -d (data) параметр тела запроса экранируется и добавляется непосредственно в команду curl, а не загружается из файла (как описано в топике: Общие команды curl, связанные с REST).

В разделе "Ответы" Swagger UI выдает ответ сервера. По умолчанию ответ возвращает XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <Pet>
    <category>
      <id>0</id>
      <name>string</name>
    </category>
    <id>1000</id>
    <name>Bentley</name>
    <photoUrls>
      <photoUrl>string</photoUrl>
    </photoUrls>
    <status>available</status>
    <tags>
      <tag>
        <id>0</id>
        <name>string</name>
      </tag>
    </tags>
  </Pet>

Если выбрать в выпадающем списке "Response content type" JSON, то в ответе вернется JSON вместо XML.

"Petstore" - является действующим API, питомец фактически создан. Для забавы развернем конечную точку GET / pet / {petId}, нажимаем Try it out, вводим идентификатор питомца, который использовали в предыдущей операции, а затем выполняем запрос. В ответе видим имя питомца, которое совпадает с тем, что ввели в предыдущем примере.

Подробная информация для этого практического занятия находится по ссылке Знакомство со спецификациями OpenAPI и Swagger

Практическое занятие "Редакция существующей спецификации API"

👨‍💻 Редакция существующей спецификации API

Используем простой Sunrise and sunset times API для знакомства с процессом создания файла спецификации OpenAPI. Sunrise and sunset times API не требует аутентификации с запросами, поэтому он удаляет некоторые из более сложных процессов аутентификации (можно пропустить объект secutity). В этом практическом занятии отредактируем некоторые из значений в уже написанной спецификации OpenAPI.

Для редактирования файла спецификации OPenAPI:

Скопируем код из pre-built OpenAPI specification
Вставляем содержимое YAML в редактор Swagger
Определяем каждый из объектов корневого уровня спецификации API:

Шаг 1: Объект openapi
Шаг 2: Объект info
Шаг 3: Объект servers
Шаг 4: Объект paths
Шаг 5: Объект components
Шаг 8: Объект externalDocs

В объекте info (сверху) внесем изменения в свойство description и посмотрим, как обновится экран в правом столбце.
В объекте parameters тоже внесем изменения в свойство description и посмотрим, как обновится экран в правом столбце.
Найдем указатель $ref в объекте response. Определим, на что он указывает в компонентах.
Добавим интервалов таким образом, чтобы сделать спецификацию недействительной (например вставим пробел перед info) и посмотрим на ошибку. Затем уберем лишний пробел.
Развернем секцию GET, нажмем Try it out и посмотрим на ответ.

Подробная информация для этого практического занятия находится по ссылке Создание спецификации OpenAPI

Практическое занятие "Заполнение интерфейса Swagger при помощи спецификации OpenAPI"

👨‍💻 Заполнение интерфейса Swagger при помощи спецификации OpenAPI

В этом упражнении создадим отображение пользовательского интерфейса Swagger для спецификации OpenAPI. Если используется один из предварительно созданных файлов OpenAPI, можно увидеть демо того, что мы создадим здесь: OpenWeatherMap Swagger UI или Sunrise/sunset Swagger UI

Демо визуализации интерфейса Swagger спецификации OpenAPI OpenWeatherMap

Для интеграции спецификации OpenAPI в Swagger UI:

Подготовим действительный документ спецификации OpenAPI:

инструкции по созданию документа спецификации OpenAPI с нуля в руководстве по OpenAPI;
для использования предварительно созданной спецификации OpenAPI можно воспользоваться файлом спецификации OpenWeatherMap или Sunrise/sunset API (правой кнопкой кликаем ссылку и сохраняем YAML на рабочем столе);

Удостоверяемся в правильности нашей спецификации. Вставляем нашу спецификацию OpenAPI в Swagger online editor и удостоверимся в отсутствии ошибок. В правой части отображается функциональный дисплей Swagger UI.
Переходим по ссылке Swagger UI GitHub project.
Нажимаем Clone или Download и затем нажимаем Download ZIP. Сохраняем архив на компьютер и извлекаем файлы.

Единственная папка, с которой будем работать в загруженном zip-архиве, - это папка dist (сокращение от дистрибутива). Все остальное используется только при компиляции файлов Swagger, что выходит за рамки этого руководства.

Перетащим папку dist из папки swagger-ui-master. (Затем при необходимости удалите папку swagger-ui-master и zip-файл.)
Перетащим файл спецификации OpenAPI (из шага 1) в папку dist. (Если вы используете предварительно созданные файлы OpenAPI, файл называется либо openapi_openweathermap.yml, либо openapi_sunrise_sunset.yml.) Файловая структура должна выглядеть следующим образом:

├── dist
│   ├── favicon-16x16.png
│   ├── favicon-32x32.png
│   ├── index.html
│   ├── oauth2-redirect.html
│   ├── swagger-ui-bundle.js
│   ├── swagger-ui-bundle.js.map
│   ├── swagger-ui-standalone-preset.js
│   ├── swagger-ui-standalone-preset.js.map
│   ├── swagger-ui.css
│   ├── swagger-ui.css.map
│   ├── swagger-ui.js
│   ├── swagger-ui.js.map
│   ├── swagger30.yml
│   └── [your openapi specification file]

В папке dist открываем файл index.html в редакторе Atom или Sublime Text
Ищем следующий код:

url: "http://petstore.swagger.io/v2/swagger.json",

Меняем значение url из http://petstore.swagger.io/v2/swagger.json на относительный путь к файлу YAML и сохраняем файл. Пример:

url: "openapi_openweathermap.yml",

или

url: "openapi_sunrise_sunset.yml",

Рассмотрим файл index.html локально в вашем браузере. Обратите внимание, что ограничения безопасности Chrome (CORS objections) не позволяют просматривать файл пользовательского интерфейса Swagger локально, но есть несколько обходных путей:

Просмотр файла локально с помощью Firefox (это самый простой способ);
Используйте размещенный в Интернете URL-адрес для openapi_openweathermap.yml или openapi_sunrise_sunset.yml. (Клик правой кнопкой мыши и выбор "Копировать адрес ссылки".);
Загружаем папку dist на веб-сервер и смотрим на нее там;
Размещаем файл YAML на публичном GitHub Gist и затем нажимаем Raw. Используем URL для этого Gist;
Используем локальный сервер, например простой локальный HTTP сервер

По готовности публиковать Swagger файл? просто загружаем папку на веб-сервер и переходим в файл index.html. Если папку не переименовали и оставили dist то переходим по адресу http://myserver.com/dist/. Переименовать папку можно в любой момент.

Подробные инструкции работы в Swagger по ссылке Swagger.io docs

Подробная информация для этого практического занятия находится по ссылке Руководство Swagger UI

Практическое занятие "Работа с OpenAPI в Stoplight"

👨‍💻 Работа с OpenAPI в Stoplight

Скачиваем и заполняем Stoplight спецификацией OPenAPI

В этом упражнении работаем с файлом OpenAPI в Stoplight, который предоставляет графический редактор для работы со спецификацией OpenAPI.

Для ускорения процесса начнем с предварительно подготовленным файлом OpenAPI, который вставим в редактор Stoplight и сделаем несколько модификаций, используя инструменты визуального моделирования Stoplight.

Stoplight имеет веб-версию и приложение для десктопа. Для простоты будем использовать веб-версию.

Для работы с OpenAPI в Stoplight:

В настоящее время Stoplight поддерживает только версию OpenAPI 2.0. Можно сконвертировать спецификацию версии 3.0 в 2.0, используя APIMATIC Transformer. Для ускорения проще скачать уже готовый файл 2.0 OpenAPI JSON file
Переходим к https://next.stoplight.io/
Нажимаем Login в правом верхнем углу и логинимся, используя аккаунт GitHub.
Нажимаем New Personal Project
Вводим Имя проекта (пример "OpenWeatherMap API"), указываем public или private видимость, и нажимаем Next.
На следующем экране (Project Designer) выбираем вкладку "Import Existing". Кликаем Upload OpenAPI (Swagger), Markdown or HTML File и выбираем файл openweathermap_swagger20.json, который загрузили в первом шаге.
Нажимаем на кнопку +openweathermap_swagger20.oas2.yml. Файл OpenAPI загружается в Stoplight, данные заполняют интерфейс Stoplight.
Вверху экрана можно переключаться между представлениями «Код» и «Дизайн», нажимая соответствующие кнопки. Внесем некоторые изменения в код, а затем переключимся в представление «Дизайн», чтобы увидеть их изменения. (Обратите внимание, что Stoplight предпочитает JSON в качестве формата кода.)

Данное видео показывает весь процесс

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

Изучим различные параметры в редакторе дизайна (в частности, развернем Пути и нажмем погода> Call current weather data for…) и внесем несколько произвольных текстовых изменений, чтобы узнать, как обновлять информацию.

Автоматически сгенерированная схема документации

Одна из самых крутых функций в Stoplight - это возможность автоматически генерировать документацию схемы из примера ответа JSON. Попробуем функцию автоматического создания, выполнив следующие действия:

В средней колонке Stoplight нажимаем PATHS, затем weather и Call current weather data for …
В секции "Ответы" нажимаем Raw Schema и удаляем существующую схему ответа (при удалении информации здесь останутся фигурные скобки {})
Переключаем на вкладку Editor и нажимаем Generate from JSON и вставим JSON ответ от конечной точки OpenWeatherMap:

{
  "coord": {
    "lon": -121.96,
    "lat": 37.35
  },
  "weather": [
    {
      "id": 801,
      "main": "Clouds",
      "description": "few clouds",
      "icon": "02d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 75.51,
    "pressure": 1014,
    "humidity": 8,
    "temp_min": 66.92,
    "temp_max": 80.6
  },
  "visibility": 16093,
  "wind": {
    "speed": 11.41,
    "deg": 330
  },
  "clouds": {
    "all": 20
  },
  "dt": 1541544960,
  "sys": {
    "type": 1,
    "id": 479,
    "message": 0.0043,
    "country": "US",
    "sunrise": 1541515128,
    "sunset": 1541552625
  },
  "id": 420006397,
  "name": "Santa Clara",
  "cod": 200
}

Нажимаем Generate!

Stoplight автоматически генерирует схему JSON, соответствующую спецификации OpenAPI. Вы только что спасли себе рабочий день!

Вот короткое видео, показывающее процесс автоматической генерации JSON. Редактор Stoplight немного эволюционировал, но он все еще очень прост. (Также обратите внимание, что вместо того, чтобы начинать с приведенного выше примера JSON, видео выполняет запрос в Postman, а затем копирует ответ оттуда - но идея должна быть ясной.)

Инструменты визуального моделирования Stoplight позволяют автоматически создавать правильное определение схемы JSON из вставленного вами блока JSON.

Перейдите на вкладку Raw Schema, чтобы увидеть код, который Stoplight автоматически написал на основе скопированного образца JSON.

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

Подробная информация для этого практического занятия находится по ссылке Stoplight - инструменты визуального моделирования для создания спецификаций

Часть 6 Концептуальный контент документации API

Практическое занятие "Оценка концептуального контента на 3 сайта API документации""

👨‍💻 Оценка концептуального контента на 3 сайта API документации

Переходим к Списку 100 сайтов API документации и выбираем 3 сайта для анализа. Можно взять сайты любимых инструментов или любимых компаний, или просто 3 рандомных сайта.
Смотрим документацию и анализируем ее состав:

Безадресные разделы	Сайт 1	Сайт 2	Сайт 3
Обзор API
Начало работы
Аутентификация и авторизация
Коды статусов и ошибок
Ограничения скорости
Описание и образцы кода
SDK и примеры приложений
Краткое справочное руководство
API глоссарий
Лучшие практики

Создайте эту таблицу в своем любимом текстовом редакторе и заполните по возможности все столбцы.

Есть ли у вас какие-либо заслуживающие внимания наблюдения из вашего анализа?

Подробная информация для этого практического занятия находится по ссылке Практическое занятие: Оценка концептуального контента в проекте

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

Практическое занятие "Поиск общих шаблонов на сайтах API"

👨‍💻 Поиск общих шаблонов на сайтах API

Переходим к списку 100 сайтов API документации
Выбираем порядка 5 сайтов из списка.
Ищем одинаковые шаблоны или части. Например можно поискать:

структура и шаблоны;
бесшовный брендинг (между сайтом с документацией и продающим сайтом);
множественные примеры кода и подсветка синтаксиса;
длинные страницы;
интерактивность API (например, API Explorer);
инструментарий Docs as code;

Замечаем и не шаблонные вещи:

PDF;
переводы;
видео инструкции;
функции комментирования;
множественные выходы по роли;

Создаем несколько заметок в логах API или журнале (или оставляем комментарии ниже)

В следующем разделе рассмотрим Шаблоны проектирования и сайты API документации

Из созданных заметок посмотрим, соответствуют ли выделенные там шаблоны тем, которые мы наблюдали на проанализированных сайтах API.

Подробная информация для этого практического занятия находится по ссылке Список из 100 сайтов с API документацией

Практическое занятие "Практикуемся в редакторе Markdown"

👨‍💻 Практикуемся в редакторе Markdown

Для понятия что такое Markdown попрактикуемся немного работая в этом редакторе.

Переходим на онлайн версию редактора (например Dillinger.io)
Создадим следующие элементы текста:

нумерованный список;
маркированный список;
жирное форматирование;
пример кода;
заголовок 2 уровня;
кодированный текст.

При желании можно скопировать содержимое файла формата .md из surfreportendpoint.md file и изучить теги редактора Markdown.

Подробная информация для этого практического занятия находится по ссылке Подробнее о Маркдаун

Практическое занятие "Настройка Wiki на GitHub"

👨‍💻 Создаем wiki на GitHub и публикуем контент на пробной странице

В этом упражнении создадим новый репозиторий на сайте GitHub и опубликуем файла.

Открываем GitHub и логинимся там. После нажимаем кнопку + и выбираем New repository

Создание нового репозитория на GitHub

Вписываем имя репозитория, краткое описание, выбираем видимость public, выбираем Initialize the repo with a README и затем нажимаем Create repository (Не стоит обращать внимания на выбор лицензии настроек gitignore для этого упражнения).
Переходим на вкладку Wiki в навигационной панели нового репозитория.
Нажимаем кнопку Create the first page (Если wiki уже существует, то нажимаем New Page).
На начальной странице Home вставляем свой документ, предпочтительно написанный в Markdown. Или можно просто перетащить содержимое страницы fake endpoint called surfreport here.
В поле Edit message вписываем краткое описание (коммит).
Нажимаем Save Page

Обратите внимание, как GitHub автоматически преобразует синтаксис Markdown в HTML и стилизует его для удобства чтения.

Можно работать с этой вики-страницей GitHub в браузере, чтобы несколько человек могли совместно работать и редактировать контент. Однако, в отличие от других вики, с помощью GitHub вы также можете перевести весь контент в автономный режим и редактировать его локально, а затем зафиксировать свои изменения и отправить их обратно в online.

Подробная информация для этого практического занятия находится по ссылке Практическое занятие: Управляем контентом в Wiki Github

Практическое занятие "Клонируем репозиторий на локальную машину"

👨‍💻 Клонируем репозиторий на локальную машину

До сих пор мы работали с GitHub в браузере. Теперь мы возьмем тот же контент и будем работать с ним локально. Это то, что делает вики GitHub уникальным среди других вики - это репозиторий Git, поэтому вы можете управлять контентом так же, как и любым другим репозиторием Git (работая локально, выдвигая, вытягивая, объединяя, разветвляя и т. Д.).

Если на компьютере до сих пор не установлен клиент Git, тогда самое время его установить. (Проверить установку можно командой git --version в командной строке. Подробно об установке Git по ссылке).
Просматривая вики-страницу GitHub в своем браузере, обратим внимание на раздел Clone this wiki locally. Нажмите кнопку буфера обмена. (Копируется URL клона в ваш буфер обмена.)

Клонируем на локальный компьютер

Вики - это имеет отдельный URL, не относящийся к репозиторию проекта. Убедитесь, что вы просматриваете вики, а не проект. URL клона будет включать .wiki.

В отличие от раздела Clone this wiki locally, кнопка «Clone in Desktop» запускает клиент GitHub Desktop и позволяет управлять репозиторием и вашими измененными файлами, фиксировать, передавать и извлекать через клиент GitHub Desktop. Об этом написано в практическом занятии Используем клиент GitHub для десктопа

Открываем командную строку

те кто пользуется Windows, открывают эмулятор терминала Git Bash,
пользователи MacOS запускают Applications > Utilities > Terminal или iTerm

Репозиторий можно скачать в корневой каталог или в любой другой (тогда в терминале нужно перейти в нужный каталог командой cd)
Вводим git clone, затем вызываем правой кнопкой мыши контекстное меню и нажимаем paste. Сохраненный в буфере URL нашей wiki добавится в строку команды (можно и вручную ввести url wiki):

git clone https://github.com/tomjoht/weatherapi.wiki.git

Нажимаем Enter и ждем пока система клонирует wiki. В это время видим на экране исполнение команды:

Cloning into 'weatherapi.wiki'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 9 (delta 0), reused 0 (delta 0), pack-reused 6
Unpacking objects: 100% (9/9), done.

В примере Git создал папку weatherapi.wiki

Клонирование вики делает копию содержимого на вашем локальном компьютере. Git - это программное обеспечение для контроля версий, поэтому у каждого есть своя собственная копия. Когда вы клонируете репозиторий, вы создаете копию на своем локальном компьютере; версия в облаке на GitHub называется «origin». Таким образом, у вас есть два экземпляра контента.

Однако, когда вы клонируете репозиторий, вы не просто копируете файлы, а инициализируете Git в папке, куда сохранен репозиторий. Инициализация Git означает, что Git создаст невидимую папку Git в этом каталоге, и Git может начать отслеживать ваши изменения в файлах, обеспечивая контроль версий. С инициализацией Git вы можете запускать команды pull, чтобы получать обновления из онлайн-хранилища (источника) в локальную копию. Вы также можете фиксировать commit свои изменения и затем вернуть их «origin».

Переходим в папку с клонированным репозиторием, чтобы посмотреть какие файлы клонированы.

Подробная информация для этого практического занятия находится по ссылке Практическое занятие: Управляем контентом в Wiki Github

Практическое занятие "Отправляем локальные изменения на удаленный репозиторий"

👨‍💻 Отправляем локальные изменения на удаленный репозиторий

В текстовом редакторе открываем наш файл, скачанный с репозитория git Hub. Файл будет открыт в приложении по умолчанию, связанном с этим типом файла. Вы также можете открыть файл, перейдя к нему вручную и открыв его, как обычно (просмотр в Finder или Explorer).
Внесем изменения и сохраним файл. Например напишем свое имя вверху документа.
В терминале удостоверимся, что находимся в нужной папке.

Для просмотра впишем команду ls под текущей строкой. Потом введем команду сd/{имя папки} для входа в папку или cd ../для перемещения на уровень выше.

Добавим все файлы:

git add .

Git не отслеживает все файлы в той папке, где он был инициализирован. Git отслеживает изменения только для файлов, которые были «добавлены» в Git. Набрав git add . или git add --all, вы говорите Git начать отслеживать изменения всех файлов в этом каталоге. Вместо этого вы также можете ввести здесь определенное имя файла, например git add Home.md, чтобы просто добавить определенный файл (а не все файлы, которые были изменены) для отслеживания в Git.

После команды git add Git добавляет файлы в так называемую область подготовки. Используя спортивную аналогию, площадка для постановки похожа на беговую дорожку. Эти файлы готовы для фиксации, когда вы запускаете git commit.

Просмотреть статус файла можно командой

git status

Git ответит сообщением, указывающим, какие файлы готовы для коммита.

Changes to be committed:
	(use "git reset HEAD <file>..." to unstage)

		modified:   Home.md

В области подготовки перечислены все файлы, которые были добавлены в Git и которые вы каким-либо образом изменили.

Рекомендуется всегда проверять git status перед фиксацией файлов, потому что вы можете понять, что, набрав git add ., Вы могли случайно добавить некоторые файлы, которые вы не собирались отслеживать (например, большие двоичные файлы). Если вы хотите удалить этот файл из промежуточной области, вы можете ввести команду git reset HEAD Home.md, чтобы удалить его.

Коммитим изменения

git commit -m "updated some content"

Коммит создает слепок файла в данный момент времени для версионирования.

Команда git commit -m является ярлыком для фиксации и ввода сообщения коммита. Обновления таким способом гораздо проще фиксировать.

Если ввести только git commit, то будет предложено ввести описание коммита в режиме редактора Bash. Опишите изменения в верхней строке, а затем сохраните и закройте окно.

На Mac новое окно не открывается. Вместо этого в терминале открывается режим редактора Vim. («Vi» обозначает visual, а «m» - режим, но это не очень визуальный редактор.) Для выхода из редактора нажимаем клавишу Escape. Затем вводим q, чтобы выйти. (См. Здесь команды Vim.) Возможно захочется настроить терминал так, чтобы открывался внешний редактор, такой как Sublime Text. Подробности в разделе Связывание текстовых редакторов с Git.

Отправляем изменения на удаленный репозиторий командой

git push

Если автоматическая аутентификация на GitHub не настроена, то будет предложено ввести ваши учетные данные: логин и пароль (Ваш username - это логин ID на GitHub).

Обратите внимание: когда вы набираете git push или git pull и не указываете ветку, GitHub использует ветку по умолчанию из источника. Ветвь по умолчанию на GitHub называется master. Таким образом, фактически переданная команда - это git push origin master (это означает: отправить эти изменения в удаленный репозиторий origin, в ветке master). Некоторые разработчики предпочитают указывать хранилище и ветвь, чтобы обеспечить взаимодействие с нужными хранилищами и ветвями.

Окно терминала на Mac, будет выглядеть примерно так:

Окно терминала с командами Git

Теперь проверим наши изменения. Заходим на удаленный репозиторий и посмотрим изменения.

Подробная информация для этого практического занятия находится по ссылке Практическое занятие: Управляем контентом в Wiki Github

Часть 8 Устройство на работу с API документацией

Практическое занятие "Обзор вакансий и требований в них к документированию API"

👨‍💻 Обзор вакансий и требований в них к документированию API

На этом занятии мы рассмотрим требования в вакансиях в выбранном регионе и составим план.

Идем на сайт indeed.com
В поле "Местоположение" введите желаемый город или локацию
Поисковые слова вводим API технический писатель или комбинации API+ Технический писатель + разработчик документации
Изучим 5 вакансии
Обратите внимание на некоторые из основных требований для этих работ.
Оцените, какими из пунктов обладаете:

Портфолио с примерами описания документации для разработчиков;
технические знания, сопоставимые с уровнем разработчика;
опыт написания документации для разработчиков.

составляем план, как привести портфолио к нужному виду, получить необходимые знания и опыт, которые описываются в вакансиях. Возможно понадобится больше практики с опен-сорс проектами

Подробная информация для этого практического занятия находится по ссылке Лучшие локации для работы

🔙

Go next ➡

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

workshop-activities.md

workshop-activities.md

Практические занятия

Часть 1 Знакомство с API документацией

Практическое занятие "Идентификация целей"

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

Практическое занятие "Исследуем API OpenWeatherMap"

Практическое занятие "Получаем ключ авторизации OpenWeatherMap"

Практическое занятие "Создаем запрос в Postman"

Создаем Запрос

Сохраняем запрос

Создаем запрос на 5-дневный прогноз

Создаем еще один запрос OpenWeatherMap

Практическое занятие 2.4. Создаем запрос в curl

Практическое занятие 2.5. Создаем AJAX-запрос и проверяем полезную нагрузку

Часть 3 Документирование конечной точки API

Практическое занятие "Поиск опен-сорс проекта"

Практическое занятие "Оценка ключевых элементов API документации""

Часть 4 OpenAPI и Swagger

Практическое занятие "Знакомство со Swagger при помощи Petstore Demo"

Практическое занятие "Редакция существующей спецификации API"

Практическое занятие "Заполнение интерфейса Swagger при помощи спецификации OpenAPI"

Практическое занятие "Работа с OpenAPI в Stoplight"

Часть 6 Концептуальный контент документации API

Практическое занятие "Оценка концептуального контента на 3 сайта API документации""

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

Практическое занятие "Поиск общих шаблонов на сайтах API"

Практическое занятие "Практикуемся в редакторе Markdown"

Практическое занятие "Настройка Wiki на GitHub"

Практическое занятие "Клонируем репозиторий на локальную машину"

Практическое занятие "Отправляем локальные изменения на удаленный репозиторий"

Часть 8 Устройство на работу с API документацией

Практическое занятие "Обзор вакансий и требований в них к документированию API"

Files

workshop-activities.md

Latest commit

History

workshop-activities.md

File metadata and controls

Практические занятия

Часть 1 Знакомство с API документацией

Практическое занятие "Идентификация целей"

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

Практическое занятие "Исследуем API OpenWeatherMap"

Практическое занятие "Получаем ключ авторизации OpenWeatherMap"

Практическое занятие "Создаем запрос в Postman"

Создаем Запрос

Сохраняем запрос

Создаем запрос на 5-дневный прогноз

Создаем еще один запрос OpenWeatherMap

Практическое занятие 2.4. Создаем запрос в curl

Практическое занятие 2.5. Создаем AJAX-запрос и проверяем полезную нагрузку

Часть 3 Документирование конечной точки API

Практическое занятие "Поиск опен-сорс проекта"

Практическое занятие "Оценка ключевых элементов API документации""

Часть 4 OpenAPI и Swagger

Практическое занятие "Знакомство со Swagger при помощи Petstore Demo"

Практическое занятие "Редакция существующей спецификации API"

Практическое занятие "Заполнение интерфейса Swagger при помощи спецификации OpenAPI"

Практическое занятие "Работа с OpenAPI в Stoplight"

Часть 6 Концептуальный контент документации API

Практическое занятие "Оценка концептуального контента на 3 сайта API документации""

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

Практическое занятие "Поиск общих шаблонов на сайтах API"

Практическое занятие "Практикуемся в редакторе Markdown"

Практическое занятие "Настройка Wiki на GitHub"

Практическое занятие "Клонируем репозиторий на локальную машину"

Практическое занятие "Отправляем локальные изменения на удаленный репозиторий"

Часть 8 Устройство на работу с API документацией

Практическое занятие "Обзор вакансий и требований в них к документированию API"