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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Открыть вкладку 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» и вставили необходимую пару ключ-значение в заголовок.)

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

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

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

1. В Postman нажать на кнопку Save (правее Send)
2. В диалоговом окне ввести имя запроса, например: “OpenWeatherMap Current API”
3. В описании запроса написать краткое описание запроса (опционально), например: “gets the current weather for 95050 in imperial units.”

4. Проскроллить окно немного вниз и нажать Create collection для создания папки, куда будет сохранен запрос. После создания выбрать созданную папку.

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

   

5. Нажать 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

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

1. Открыть Postman
2. В любом запросе кликаем на кнопку Code под кнопкой Save
3. В диалоговом окне “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"

1. Curl доступен на MacOS по умолчанию. Если на Windows curl еще не установлен, то инструкции по установке по ссылке, нужно выбрать одну из бесплатных версий с правами Администратора.
2. Открываем терминал
   • на 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 по этой теме.

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

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

👨‍💻 Создаем запрос на странице с помощью 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

👨‍💻 Практическое занятие “Что не так в разделе API?”

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

Что не так с разделом API?

Ниже приведен пример справочной темы по API для конечной точки, которая называется surfreport. Там есть примерно 25 ошибок. Копия документации доступна в Google Docs только для чтения. В Google Docs можно перейти в File> Make a Copy, чтобы создать свой собственный экземпляр. Затем прокомментировать все ошибки в файле Google Docs.

Surfreport

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

Конечные точки

GET/POST surfreport/{:beachId}

Параметры

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

https://api.openweathermap.org/data/2.5/surfreport/12345?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&days=1

Пример ответа

{
    "surfreport": [
        {
            "beach": "Santa Cruz",
            "monday": {
                "1pm": {
                    "tide": 5,
                    "wind": 15,
                    "watertemp": 80,
                    "surf_height": 5,
	          "riptide": "moderate",
                    "recommendation": "Carve it up, brah! The waves are crankin' wild out there."
                },
                "2pm": {
                    "tide": -1,
                    "wind": 1,
                    "watertemp": 50,
                    "surf_height": 3,
	          "riptide": "extreme",
                    "recommendation": "Waves are foam and frothy but rideable in places. Gravitate to the impact zone, due, and hang loose."
                },
                "3pm": {
                    "tide": -1,
                    "wind": 10,
                    "watertemp": 65,
                    "surf_height": 1,
                    "recommendation": "Scene is blown out. Bail inland and chill on the beach instead or you’ll the one who’ll be shredded, due."
                }
                ...
            }
        }
    ]
}

Определения ответа

В таблице ниже пояснения по каждому пункту ответа

Ответы

Посмотреть ошибки можно в разделе Описание ошибок

👨‍💻 Ищем опен-сорс проект с необходимостью документирования 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 и определить общие элементы. Для оценки документации:

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

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

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

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

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

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

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

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

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

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

Используем простой 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

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

Для интеграции спецификации 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

👨‍💻 Оценка контента 3 сайтов API документации

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

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

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

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

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

• Переходим к списку 100 сайтов API документации
• Выбираем порядка 5 сайтов из списка.
• Ищем одинаковые шаблоны или части. Например можно поискать:
  • структура и шаблоны;
  • бесшовный брендинг (между сайтом с документацией и продающим сайтом);
  • множественные примеры кода и подсветка синтаксиса;
  • длинные страницы;
  • интерактивность API (например, API Explorer);
  • инструментарий Docs as code;
• Замечаем и не шаблонные вещи:
  • PDF;
  • переводы;
  • видео инструкции;
  • функции комментирования;
  • множественные выходы по роли;
• Создаем несколько заметок в логах API или журнале (или оставляем комментарии ниже)

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

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

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

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

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

• Переходим на онлайн версию редактора (например Dillinger.io)
• Создадим следующие элементы текста:
  • нумерованный список;
  • маркированный список;
  • жирное форматирование;
  • пример кода;
  • заголовок 2 уровня;
  • кодированный текст.
• При желании можно скопировать содержимое файла формата .md из surfreportendpoint.md file и изучить теги редактора Markdown.

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

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

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

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

• Вписываем имя репозитория, краткое описание, выбираем видимость 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, будет выглядеть примерно так:

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

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

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

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

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

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