├── Getting-job ├── README.md ├── best-locations.md ├── how-much-code-to-know.md ├── img │ ├── 1.png │ ├── 2.jpg │ └── 3.png └── job-market.md ├── LICENSE ├── Native-library ├── Activity-Generate-Javadoc.md ├── Create-non-refsdocs-with-native-library-APIs.md ├── Doxygen.md ├── Explore-Javadoc-output.md ├── Get-the-sample-Java-project.md ├── Java-crash-course.md ├── Javadoc-tags.md ├── Make-edits-Javadocs-tags.md ├── Overview-of-library.md ├── README.md └── img │ ├── 1.png │ ├── 10.png │ ├── 11.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 15.png │ ├── 16.png │ ├── 2.png │ ├── 3.png │ ├── 4.png │ ├── 5.png │ ├── 6.png │ ├── 7.png │ ├── 8.png │ └── 9.png ├── Publishing-doc ├── API-doc-sites-list.md ├── Design-patterns.md ├── Doc-as-code-tools.md ├── Headless-cms-options.md ├── Hosting-and-deployment-options.md ├── Jekyll-and-cloudCannon.md ├── Manage-wiki-content.md ├── More-about-Markdown.md ├── Overview-for-publishing.md ├── Pull-request-workflows.md ├── README.md ├── Static-site-generators.md ├── Switching-tools.md ├── Use-GitHub-Desktop.md ├── Version-control-system.md ├── Which-tool-choose.md └── pics │ ├── 1.png │ ├── 10.jpg │ ├── 10.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 15.png │ ├── 16.png │ ├── 17.png │ ├── 18.png │ ├── 19.png │ ├── 2.png │ ├── 20.png │ ├── 21.png │ ├── 22.png │ ├── 23.png │ ├── 24.png │ ├── 25.png │ ├── 26.png │ ├── 27.png │ ├── 28.png │ ├── 29.png │ ├── 3.png │ ├── 30.png │ ├── 31.png │ ├── 32.png │ ├── 33.png │ ├── 34.png │ ├── 35.png │ ├── 36.png │ ├── 37.png │ ├── 38.png │ ├── 39.png │ ├── 4.png │ ├── 40.png │ ├── 41.png │ ├── 42.png │ ├── 43.png │ ├── 44.png │ ├── 45.png │ ├── 46.png │ ├── 47.png │ ├── 48.png │ ├── 49.png │ ├── 5.png │ ├── 50.png │ ├── 51.png │ ├── 52.png │ ├── 53.png │ ├── 54.png │ ├── 55.png │ ├── 6.png │ ├── 7.png │ ├── 8.png │ └── 9.png ├── README.md ├── conceptual-topics ├── API-overview.md ├── README.md ├── api-glossary.md ├── assess-conceptual-content.md ├── authentication-and-authorization.md ├── best-practices.md ├── code-samples.md ├── getting-started.md ├── img │ ├── 1.jpg │ ├── 10.png │ ├── 11.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 15.jpg │ ├── 16.jpg │ ├── 17.jpg │ ├── 18.png │ ├── 19.jpg │ ├── 2.png │ ├── 20.png │ ├── 21.png │ ├── 22.png │ ├── 23.png │ ├── 24.jpg │ ├── 25.png │ ├── 26.png │ ├── 27.png │ ├── 28.png │ ├── 29.png │ ├── 3.png │ ├── 30.jpg │ ├── 31.png │ ├── 32.png │ ├── 33.png │ ├── 34.jpg │ ├── 35.png │ ├── 36.png │ ├── 37.png │ ├── 38.png │ ├── 39.png │ ├── 4.png │ ├── 40.png │ ├── 41.jpg │ ├── 42.png │ ├── 43.png │ ├── 44.png │ ├── 45.png │ ├── 46.png │ ├── 47.png │ ├── 48.jpg │ ├── 49.png │ ├── 5.jpg │ ├── 50.png │ ├── 51.png │ ├── 52.png │ ├── 53.png │ ├── 54.jpg │ ├── 55.png │ ├── 56.png │ ├── 57.png │ ├── 58.jpg │ ├── 59.png │ ├── 6.jpg │ ├── 60.png │ ├── 7.png │ ├── 8.png │ └── 9.png ├── quick-reference-guide.md ├── rate-limiting.md ├── sdks-sample-apps.md ├── status-error-codes.md └── user-guide-topics.md ├── doc-code ├── README.md ├── doc-code.md ├── doc-research.md ├── doc-strategy.md └── img │ └── 1.jpg ├── documenting-api-endpoints ├── README.md ├── api-reference-tutorial-overview.md ├── evaluate-api-referense-docs.md ├── find-open-source-project.md ├── new-endpoint.md ├── pics │ ├── 1.png │ ├── 10.png │ ├── 11.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 15.png │ ├── 16.png │ ├── 17.png │ ├── 18.png │ ├── 19.png │ ├── 2.png │ ├── 20.png │ ├── 21.png │ ├── 22.png │ ├── 23.png │ ├── 24.png │ ├── 25.png │ ├── 26.png │ ├── 27.png │ ├── 28.png │ ├── 29.png │ ├── 3.png │ ├── 30.png │ ├── 31.png │ ├── 32.png │ ├── 33.png │ ├── 34.png │ ├── 35.png │ ├── 36.png │ ├── 37.png │ ├── 38.png │ ├── 4.png │ ├── 5.png.jpg │ ├── 6.png │ ├── 7.png │ ├── 8.png │ └── 9.png ├── putt-all-together.md ├── step1-resourse-description.md ├── step2-endpoints-and-methods.md ├── step3-parameters.md ├── step4-request-example.md ├── step5-response-example-and-schema.md └── whats-wrong.md ├── glossary-and-resourses ├── API-Blueprint-tutorial.md ├── Get-event-information-using-Eventbrite-API.md ├── Get-wind-speed-using-Aeris-API.md ├── Glossary-for-API-documentation.md ├── RAML-tutorial.md ├── README.md ├── RESTAPI-activities.md ├── Retrieve-gallery-using-Flickr-API.md ├── answeres-whats-wrong.md └── img │ ├── 1.png │ ├── 10.png │ ├── 11.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 15.png │ ├── 16.png │ ├── 17.png │ ├── 18.png │ ├── 19.png │ ├── 2.png │ ├── 20.png │ ├── 21.png │ ├── 22.png │ ├── 3.png │ ├── 4.png │ ├── 5.png │ ├── 6.png │ ├── 7.png │ ├── 8.png │ └── 9.png ├── introduction-rest-apis ├── README.md ├── about-the-author.md ├── api-doc-market.md ├── course-overview.md ├── course-slides.md ├── identify-goals.md ├── pics │ ├── 10.png │ ├── 11.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 15.png │ ├── 16.png │ ├── 17.png │ ├── 18.png │ ├── 19.png │ ├── 2.jpg │ ├── 20.png │ ├── 21.png │ ├── 22.png │ ├── 23.png │ ├── 24.png │ ├── 25.png │ ├── 26.jpg │ ├── 27.png │ ├── 28.jpg │ ├── 29.jpg │ ├── 3.png │ ├── 30.jpg │ ├── 31.jpg │ ├── 32.jpg │ ├── 33.jpg │ ├── 34.jpg │ ├── 35.jpg │ ├── 36.jpg │ ├── 37.jpg │ ├── 38.jpg │ ├── 4.png │ ├── 5.png │ ├── 6.png │ ├── 7.png │ ├── 8.png │ └── 9.png ├── video-presentations.md ├── what-for-this-course.md ├── what-is-rest-api.md └── workshop-activities.md ├── like-developer ├── README.md ├── access-print-value.md ├── analyze-json-response.md ├── curl-intro-and-instalation.md ├── dot-notation.md ├── get-authorization-keys.md ├── inspect-json.md ├── make-curl-call.md ├── pics │ ├── 1.jpg │ ├── 10.png │ ├── 11.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 2.jpg │ ├── 2.png │ ├── 3.png │ ├── 4.png │ ├── 5.png │ ├── 6.png │ ├── 7.png │ ├── 8.png │ └── 9.png ├── submit-requests-postman.md ├── understand-curl.md ├── use-methods-with-curl.md └── using-api-scenario.md ├── openAPI-specification ├── README.md ├── create-openapi-specification.md ├── img │ ├── 1.png │ ├── 10.png │ ├── 11.png │ ├── 12.png │ ├── 13.png │ ├── 14.png │ ├── 15.png │ ├── 16.png │ ├── 17.png │ ├── 18.png │ ├── 19.png │ ├── 2.jpg │ ├── 20.png │ ├── 21.png │ ├── 22.png │ ├── 23.png │ ├── 24.png │ ├── 25.png │ ├── 26.png │ ├── 27.png │ ├── 28.png │ ├── 29.png │ ├── 3.png │ ├── 30.png │ ├── 31.png │ ├── 32.png │ ├── 33.png │ ├── 34.png │ ├── 35.png │ ├── 4.png │ ├── 5.png │ ├── 6.png │ ├── 7.png │ ├── 8.png │ ├── 9.png │ └── youtube.jpg ├── integrating-swagger-with-docs.md ├── introduction-openapi-and-swagger.md ├── openapi-tutorial-overview.md ├── overview-specification-formats.md ├── step1-openapi-object.md ├── step2-info-object.md ├── step3-servers-object.md ├── step4-paths-object.md ├── step5-components-object.md ├── step6-security-object.md ├── step7-tags-object.md ├── step8-externalDocs-object.md ├── stoplight.md ├── swagger-ui-demo.md ├── swagger-ui-tutorial.md ├── swaggerhub-introduction-and-tutorial.md └── working-in-YAML.md └── testing-api-doc ├── README.md ├── img ├── 1.jpg ├── 2.png ├── 3.png └── 4.png ├── overview-testing.md ├── set-up-test-environment.md ├── test-assumptions.md ├── test-documentation.md └── test-instructions-yourself.md /Getting-job/README.md: -------------------------------------------------------------------------------- 1 | # Работа техписателя 2 | 3 | Чтобы получить работу, имеющую отношение к документации API, нужно продемонстрировать портфолио и технические способности . 4 | 5 | В портфолио должны быть включены образцы документации, написанной для разработчиков. 6 | 7 | Одним из способов создания такого портфолио является работа над проектом с открытым исходным кодом. Желательно находиться в техническом центре, где доступны задания по документации API, например, в Калифорнии, Техасе, Нью-Йорке или Вирджинии. 8 | 9 | В целом, развитие в мире документации для разработчиков потребует постоянного изучения здоровой порции кода, несмотря на свою сложность. 10 | 11 | # Содержание модуля "Работа техписателя" 12 | 13 | [**Рынок труда технического писателя**](job-market.md) 14 | 15 | [**Необходимое количество кода, которое нужно знать**](how-much-code-to-know.md) 16 | 17 | [**Лучшие локации для работы**](best-locations.md) 18 | -------------------------------------------------------------------------------- /Getting-job/best-locations.md: -------------------------------------------------------------------------------- 1 | # Лучшие локации для работы 2 | 3 | Это раздел я (переводчик курса) не стал переводить, т.к. автор кусра предоставлял свои данные по США. 4 | 5 | Есть предложение наполнять этот раздел своими совместными усилиями заинтересованных технических писателей из России о Российских условиях работы технических писателей. 6 | -------------------------------------------------------------------------------- /Getting-job/img/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Getting-job/img/1.png -------------------------------------------------------------------------------- /Getting-job/img/2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Getting-job/img/2.jpg -------------------------------------------------------------------------------- /Getting-job/img/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Getting-job/img/3.png -------------------------------------------------------------------------------- /Native-library/Create-non-refsdocs-with-native-library-APIs.md: -------------------------------------------------------------------------------- 1 | # Создание концептуальной документации при помощи исходных библиотек API 2 | 3 | Хотя большое внимание уделяется справочной документации API, основная часть документации, над которой работают технические писатели (в отличие от разработчиков), является [концептуальной документацией](../conceptual-topics/README.md). Разработчики редко пишут концептуальную или обучающую документацию. 4 | 5 | Инженеры могут написать краткое описание класса в файл и сгенерируют [Javadoc](Activity-Generate-Javadoc.md). А потом передадут этот Javadoc пользователю, как если бы он представлял собой полный набор документации, хотя справочная документация не расскажет и половину истории. 6 | 7 | [Справочная документация может быть иллюзией реальной документации](#illusion) 8 | 9 | [Справочная документация основана на функциях, а не задачах](#feature) 10 | 11 | 12 | ## Справочная документация может быть иллюзией реальной документации 13 | 14 | [Jacob Kaplan Moss считает](https://jacobian.org/2009/nov/10/what-to-write/), что справочная документация может быть иллюзией реальной документации: 15 | 16 | > … автоматически сгенерированная документация более чем бесполезна: она позволяет разработчикам обманывать себя, думая, что у них есть документация, тем самым откладывая написание хороших справок вручную. Если у вас нет документации, просто признайтесь в этом. Может быть, волонтер предложит написать что-нибудь! Но не ври и дай мне эту дерьмовую автоматически сгенерированную документацию. - Джейкоб Каплан Мосс 17 | 18 | Другие тех.писатели, похоже, имеют схожие мнения. В целом, генераторы документации не сообщают намного больше, чем можно узнать, просматривая исходный код. Некоторые люди даже называют автоматически сгенерированные документы прославленным браузером исходного кода. 19 | 20 | 21 | ## Справочная документация основана на функциях, а не задачах 22 | 23 | Одна из основных проблем со справочной документацией заключается в том, что она основана на функциях, а не на задачах. Что эквивалентно перемещениям по вкладкам через интерфейс и описанию того, что находится на каждой вкладке, что находится в каждом меню и так далее. Такой способ доступа к документации является неэффективным, поскольку пользователи часто организуют свою ментальную модель по задачам, которые они хотят выполнить. 24 | 25 | Создавая документацию API, стоит подумать о задачах, которые пользователи захотят выполнить, а затем упорядочить информацию. Нужно обращаться к конечным точкам, объясняя, как выполнять задачи. Пользователи будут ссылаться на справочные документы при поиске правильных параметров, типов данных и других сведений о классе. Но только справочные документы не помогут им в выполнении задач. 26 | -------------------------------------------------------------------------------- /Native-library/Doxygen.md: -------------------------------------------------------------------------------- 1 | # Doxygen, генератор документации в основном для С++ 2 | 3 | Альтернативой Javadoc является Doxygen. Doxygen очень похож на Javadoc, за исключением того, что он может обрабатывать больше языков (Java, C++, C# и другие). Doxygen чаще всего используется для C++. Кроме того, есть инструмент с графическим интерфейсом под названием Doxywizard, который облегчает создание файла. 4 | 5 | [Скачиваем Doxywizard](#Doxywizard) 6 | 7 | [Автоматическая интеграция сборок](#integrating) 8 | 9 | [Другие генераторы документации](#otherGenerators) 10 | 11 | 12 | ## Скачиваем Doxywizard 13 | 14 | При скачивании Doxygen также получаем и Doxywizard. Дополнительные ссылки для скачивания можно найти на странице загрузок [Doxygen](http://www.doxygen.nl/download.html). 15 | 16 | Интерфейс генератора Doxywizard выглядит так: 17 | 18 | ![Doxywizard](img/15.png) 19 | 20 | Отображение документации Doxygen будет таким: 21 | 22 | ![Doxygen](img/16.png) 23 | 24 | Сам Doxywizard необязательно использовать. Можно генерировать Doxygen с помощью файла конфигурации. Как правило, разработчики запускают сборки Doxygen с сервера. 25 | 26 | В отличие от Javadoc, Doxygen позволяет включать внешние файлы, записанные в Markdown. И Doxygen предоставляет функцию поиска. Это две особенности, которые отсутствуют в Javadoc. 27 | 28 | Doxygen поддерживается одним разработчиком и, как и Javadoc, не сильно изменился за долгие годы. Интерфейс может быть, сильно устарел и несколько запутан. Но разработчики C++ привыкнут к этому. 29 | 30 | 31 | ## Автоматическая интеграция сборок 32 | 33 | Во многих IT-компаниях генераторы документов автоматически интегрируются в процесс сборки программного обеспечения. Doxygen позволяет создавать файл конфигурации, который можно запускать из командной строки (без помощи графического интерфейса). Это означает, что когда разработчики собирают программное обеспечение, справочная документация автоматически создается и включается в выходные данные. 34 | 35 | 36 | ## Другие генераторы документации 37 | 38 | Не нужно ограничивать себя либо Javadoc, либо Doxygen. Существуют десятки различных генераторов документов для разных языков. По запросу «генератор документов + {язык программирования}» можно найти много инструментов. Тем не менее, не стоит увлекаться такими инструментов. Генераторы документов несколько устарели, создают статические интерфейсы, которые выглядят такими же устаревшими, часто написаны инженерами для других инженеров и не очень гибкие. 39 | 40 | Возможно, самым большим разочарованием для генераторов документов является то, что в них нельзя интегрировать остальную часть своей документации. Например, застряли с выводом справочной документации. Еще необходимо сгенерировать практические руководства и другие учебные пособия, а затем создать ссылку на справочную документацию. Таким образом, не будет единого интегрированного опыта документирования. Кроме того, будет трудно создавать встроенные ссылки в разделах между двумя выходами. Тема фрагментации результатов подробно рассматривали в разделе [Интеграция Swagger с документацией](../openAPI-specification/integrating-swagger-with-docs.md). 41 | -------------------------------------------------------------------------------- /Native-library/Explore-Javadoc-output.md: -------------------------------------------------------------------------------- 1 | # Изучение вывода Javadoc 2 | 3 | Выходные данные Javadoc не сильно изменились за последние 20 лет, поэтому в некотором смысле они предсказуемы и знакомы. С другой стороны, выходные данные устарели и в них отсутствуют некоторые важные функции, такие как поиск или возможность добавления дополнительных страниц. В этой теме мы рассмотрим, как организован Javadoc. 4 | 5 | [Резюме класса](#summary) 6 | 7 | [Детали класса](#details) 8 | 9 | [Другая навигация](#navigation) 10 | 11 | 12 | ## Резюме класса 13 | 14 | Открываем файл `index.html`в папке Javadoc, которую сгенерировали на [практическом занятии: Генерация Javadoc из примера проекта](Activity-Generate-Javadoc.md) 15 | 16 | Вкладка "Резюме класса" показывает краткую версию каждого из классов. Описание, которое писали для каждого класса, отображается здесь. Это своего рода краткое справочное руководство по API. 17 | 18 | ![class summary](img/12.png) 19 | 20 | Для отображения деталей класса кликаем по его имени (в нашем примере это `ACMESmartphone` или `Dynamite`) 21 | 22 | 23 | ## Детали класса 24 | 25 | При просмотре страницы класса, мы получаем сводку полей, конструкторов и методов для класса. Опять же, это просто обзор. Если прокрутить вниз, то увидим полную информацию о каждом из этих элементов. 26 | 27 | ![class details](img/13.png) 28 | 29 | 30 | ## Другая навигация 31 | 32 | 33 | Если кликнуть на вкладку **Package** вверху, можно просмотреть классы по пакетам. Или можно перейти к классу, щелкнув имя класса в левом столбце. Также можно просмотреть все, кликнув **Index**. 34 | 35 | ![navigation](img/14.png) 36 | 37 | Для получения справки по организации Javadoc нужно кликнуть на вкладку **Help** вверху на навигационной панели. 38 | -------------------------------------------------------------------------------- /Native-library/Get-the-sample-Java-project.md: -------------------------------------------------------------------------------- 1 | # Получаем пример Java проекта 2 | 3 | Чтобы понять документацию API Java, полезно увидеть контекст того, что описывает документация. Как различные теги отображаются в Javadoc изучим на примере Java-приложения [sample-java-project](https://github.com/tomjoht/sample-java-project). 4 | 5 | [Пример проекта Java](#sample) 6 | 7 | [Скачиваем и открываем проект в Eclipse](#open) 8 | 9 | [Изучаем пример проекта Java](#play) 10 | 11 | [Дополнительная информация о проектах Maven](#notes) 12 | 13 | 14 | ## Пример проекта Java 15 | 16 | Пример проекта (доступен по адресу [github.com/tomjoht/sample-java-project](https://github.com/tomjoht/sample-java-project) ) представляет собой небольшое Java-приложение с различными инструментами, которые койот будет использовать для захвата птицы-бегуна. Существует два класса (`ACMESmartphone` и `Dynamite`) и другой класс с именем `App`, который ссылается на классы. 17 | 18 | Эта программа только печатает небольшие сообщения в консоли, и она достаточно проста, чтобы быть поучительной. Цель приложения - продемонстрировать различные теги документов, их размещение и способы их визуализации в Javadoc. 19 | 20 | 21 | ## 👨‍💻 Скачиваем и открываем проект в Eclipse 22 | 23 | Одной из непосредственных задач технического писателя при редактировании Javadoc является открытие проекта и получение исходного кода в IDE. 24 | 25 | 1. Переходим к [примеру проекта](https://github.com/tomjoht/sample-java-project) и клонируем проект используя контроль версий 26 | 27 | ``` 28 | git clone https://github.com/tomjoht/sample-java-project 29 | ``` 30 | 31 | Узнать основы контроля версий можно в разделе [Система контроля версий (пример Git)](../Publishing-doc/Version-control-system.md) 32 | 33 | 2. Если IDE Eclipse еще не установлен, самое время его [установить](Overview-of-library.md#eclipse). 34 | 35 | 3. Открываем Eclipse и переходим к проекту: **File > New > Java Project** 36 | 37 | 4. Снимаем галочку в чекбоксе **Use default location** и нажимаем кнопку `Browse...` для выбора папки, где находится клон проекта. Нажимаем кнопку `Open` 38 | 39 | ![open](img/3.png) 40 | > Импорт проекта 41 | 42 | 43 | 5. Нажимаем кнопку `Finish` чтобы закрыть диалоговое окно. 44 | 45 | Файлы проекта видны в левой панели (Package Explorer) Eclipse. 46 | 47 | ![open](img/4.png) 48 | > Вид IDE Eclipse 49 | 50 | 51 | ## 👨‍💻 Изучаем пример проекта Java 52 | 53 | Это Java-приложение не много умеет. Его единственная цель - создать несколько классов, которые демонстрируют некоторые аннотации Javadoc. Запустим приложение для ознакомления. 54 | 55 | 1. В левой панели откроем **javadoc_tags**. 56 | 2. Дважды кликнем по файлу **App.java** для его открытия. 57 | 3. Нажимаем кнопку **Run App** 58 | 59 | ![open](img/5.png) 60 | > Запуск приложения в Eclipse 61 | 62 | Основной метод (`public static void main (String [] args) вызывает IOException`), который появляется в файле **App.java**, выполняет функции, определенные в файлах другого пакета (`ACMESmartphone.java` и `Dynamite.java`). 63 | 64 | ``` 65 | public static void main(String[] args) throws IOException { 66 | 67 | // First initialize your smartphone using the model number and license key. 68 | ACMESmartphone myACMESmartphone = new ACMESmartphone(2.0, "398978fdskj"); 69 | 70 | // Locate the roadrunner. 71 | myACMESmartphone.findRoadRunner("Santa Clara","California"); 72 | 73 | // Zap the roadrunner with the amount of voltage you want. 74 | myACMESmartphone.zapRoadRunner(40); 75 | 76 | } 77 | ``` 78 | 79 | Просмотреть подробную информацию о каждой функции можно щелкнув файлы классов `ACMESmartphone.java` и `Dynamite.java`. 80 | 81 | Затем приложение выводит следующий текст в консоль: 82 | 83 | ``` 84 | model2.0 now initialized for license 398978fdskj 85 | location: Santa Clara, California 86 | getting geocoordinates of roadrunner.... 87 | roadrunner located at Longitude = 39.2334, Latitude = 41.4899 88 | Backfire!!! zapping coyote with 1,000,000 volts!!!! 89 | ``` 90 | 91 | ![open](img/6.png) 92 | > Выполнение программы 93 | 94 | 95 | ## Дополнительная информация о проектах Maven 96 | 97 | Прежде чем закончить вводную тему о начале работы с Java-проектом, стоит сделать заметку о Maven. Проекты Java часто имеют много зависимостей от пакетов, которые являются сторонними библиотеками или, по крайней мере, нестандартными утилитами Java. Вместо того, чтобы требовать от пользователей загрузки дополнительных пакетов и добавления их в свой класс вручную, разработчики часто используют Maven для управления пакетами. (Maven для Java, как Gradle для Android.) 98 | 99 | В проектах Maven используется файл pom.xml, который определяет зависимости. Eclipse поставляется с уже установленным Maven, поэтому, импортируя проект Maven и устанавливая его, плагин Eclipse Maven извлекает все зависимости проекта и добавляет их в наш проект. 100 | 101 | Разбираемый здесь [образец проекта](https://github.com/tomjoht/sample-java-project) не использует Maven, но есть вероятность, что, получая проект Java от разработчиков, вы не импортируете его так, как описано ранее. Вместо этого он импортируется как существующий проект Maven. 102 | 103 | Чтобы импортировать проект Maven в Eclipse, нужно перейти в меню **File > Import > Maven > Existing Maven Projects** и нажать кнопку **Next**. В поле «Корневой каталог» нажать **Browse** и перейти к папке проекта Java (которая содержит компонент Maven. XML-файл), а затем нажать кнопку **Open**. Затем нажать кнопку **Finish** в диалоговом окне. В левой панели Eclipse нужно кликнуть правой кнопкой мыши по папке Java и выбрать **Run as Maven Install**. Maven извлекает необходимые пакеты и создает проект. Если сборка прошла успешно, в консоли появится сообщение «BUILD SUCCESS» . После чего можно использовать исходный код в собранном проекте. 104 | -------------------------------------------------------------------------------- /Native-library/Make-edits-Javadocs-tags.md: -------------------------------------------------------------------------------- 1 | # Редактирование тэгов Javadoc 2 | 3 | Разработчики довольно часто добавляют тэги Javadoc и краткие комментарии, когда они создают код Java. Фактически, если они не добавляют некоторые аннотации, среда IDE обычно выдает предупреждение об ошибке. 4 | 5 | Однако комментарии, которые добавляют разработчики, могут быть плохими, неполными или непонятными. Работа технического писателя с Javadoc часто заключается в редактировании уже существующего контента, обеспечивая большую ясность, структуру, вставляя правильные теги и многое другое. 6 | 7 | [На что обращать внимание при редактировании Javadoc](#edit) 8 | 9 | [Редактируем Javadoc](#makeEdits) 10 | 11 | 12 | ## На что обращать внимание при редактировании Javadoc 13 | 14 | При редактировании Javadoc обращаем внимание на: 15 | 16 | - отсутствие документации (большая часть Javdoc неполная, нужно искать недостающую документацию); 17 | - последовательный стиль (соответствуют ли существующие тэги [соглашениям стиля Java с аннотациями](Javadoc-tags.md) ) 18 | - ясность (некоторые описания неразборчивы из-за проклятия знаний, и без хорошего понимания Java может быть трудно разобраться в них). 19 | 20 | 21 | ## Редактируем Javadoc 22 | 23 | Сделаем несколько изменений в классе и методе. Затем заново сгенерируем Javadoc и посмотрим на изменения, как они отображаются на выходе. 24 | 25 | > Как экспортировать Javadoc можно посмотреть в разделе [Практическое занятие: Генерация Javadoc из примера проекта](Activity-Generate-Javadoc.md). Каждый раз, экспортируя Javadoc, нужно выбирать какие классы включать. 26 | -------------------------------------------------------------------------------- /Native-library/README.md: -------------------------------------------------------------------------------- 1 | # Нативные библиотеки API 2 | 3 | API нативных библиотек относятся к Java, C ++ или другим API, специфичным для программирования. 4 | 5 | При таком подходе вместо запроса информации через Интернет, библиотека кода загружается и интегрируется в проект. 6 | 7 | Библиотека компилируется непосредственно в сборку приложения (а не доступна через веб-протоколы, как с REST API). Хотя этот тип API встречается реже, он включен здесь частично, для пояснения, что отличает API REST от API нативных библиотек. 8 | 9 | # Содержание модуля "Исходные библиотеки API" 10 | 11 | [**Обзор нативных библиотек API**](Overview-of-library.md) 12 | 13 | [**Получаем пример Java проекта**](Get-the-sample-Java-project.md) 14 | 15 | [**Java Ускоренный курс**](Java-crash-course.md) 16 | 17 | [**Практическое занятие: Генерация Javadoc из примера проекта**](Activity-Generate-Javadoc.md) 18 | 19 | [**Теги Javadoc**](Javadoc-tags.md) 20 | 21 | [**Изучение вывода Javadoc**](Explore-Javadoc-output.md) 22 | 23 | [**Редактирование тегов Javadoc**](Make-edits-Javadocs-tags.md) 24 | 25 | [**Doxygen, генератор документации для С++**](Doxygen.md) 26 | 27 | [**Создание концептуальной документации при помощи исходных библиотек API**](Create-non-refsdocs-with-native-library-APIs.md) 28 | -------------------------------------------------------------------------------- /Native-library/img/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/1.png -------------------------------------------------------------------------------- /Native-library/img/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/10.png -------------------------------------------------------------------------------- /Native-library/img/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/11.png -------------------------------------------------------------------------------- /Native-library/img/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/12.png -------------------------------------------------------------------------------- /Native-library/img/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/13.png -------------------------------------------------------------------------------- /Native-library/img/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/14.png -------------------------------------------------------------------------------- /Native-library/img/15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/15.png -------------------------------------------------------------------------------- /Native-library/img/16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/16.png -------------------------------------------------------------------------------- /Native-library/img/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/2.png -------------------------------------------------------------------------------- /Native-library/img/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/3.png -------------------------------------------------------------------------------- /Native-library/img/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/4.png -------------------------------------------------------------------------------- /Native-library/img/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/5.png -------------------------------------------------------------------------------- /Native-library/img/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/6.png -------------------------------------------------------------------------------- /Native-library/img/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/7.png -------------------------------------------------------------------------------- /Native-library/img/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/8.png -------------------------------------------------------------------------------- /Native-library/img/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Native-library/img/9.png -------------------------------------------------------------------------------- /Publishing-doc/README.md: -------------------------------------------------------------------------------- 1 | # Публикация документации 2 | 3 | Документация по API часто соответствует принципу docs-as-code, где инструменты для создания и публикации документации тесно связаны с теми же инструментами, которые разработчики используют для написания, управления, построения и развертывания кода. 4 | 5 | Docs-as-code включает в себя использование облегченных форматов, таких как Markdown, совместную работу с помощью Git или других систем управления версиями, создание сайта документации с помощью генератора статического сайта и развертывание его с помощью модели непрерывной сборки, где сборка происходит на сервере при фиксировании изменений в определенной ветви. 6 | 7 | # Содержание модуля "Публикация документации" 8 | 9 | [**Обзор вариантов публикации документации**](Overview-for-publishing.md) 10 | 11 | [**Список из 100 сайтов с API документацией**](API-doc-sites-list.md) 12 | 13 | [**Шаблоны проектирования сайтов API документации**](Design-patterns.md) 14 | 15 | [**Инструменты Docs-as-code**](Doc-as-code-tools.md) 16 | 17 | [**Подробнее о Markdown**](More-about-Markdown.md) 18 | 19 | [**Система контроля версий (пример Git)**](Version-control-system.md) 20 | 21 | [**Практическое занятие: Управляем контентом в Wiki Github**](Manage-wiki-content.md) 22 | 23 | [**Практическое занятие: Используем клиент GitHub для десктопа**](Use-GitHub-Desktop.md) 24 | 25 | [**Практическое занятие: процесс Pull request на GitHub**](Pull-request-workflows.md) 26 | 27 | [**Генераторы статичных сайтов**](Static-site-generators.md) 28 | 29 | [**Варианты хостинга и развертывания**](Hosting-and-deployment-options.md) 30 | 31 | [**Возможности автономных CMS**](Headless-cms-options.md) 32 | 33 | [**Рекомендации - какой инструмент документирования выбирать**](Which-tool-choose.md) 34 | 35 | [**Непрерывное развертывание Jekyll и CloudCannon**](Jekyll-and-cloudCannon.md) 36 | 37 | [**Кейс для изучения: Переход на Docs-as-code**](Switching-tools.md) 38 | 39 | [🔙](../conceptual-topics/assess-conceptual-content.md) 40 | 41 | [Go next ➡](Overview-for-publishing.md) 42 | -------------------------------------------------------------------------------- /Publishing-doc/Version-control-system.md: -------------------------------------------------------------------------------- 1 | # Система контроля версий (пример Git) 2 | 3 | Почти каждая ИТ-команда использует ту или иную форму контроля версий при разработке программного кода. Контроль версий - это то, как разработчики сотрудничают и управляют своей работой. Используя инструменты docs-as-code подразумевает и контроль версий, самым популярным инструментом которого является Git. Поскольку контроль версий является таким важным элементом для изучения, мы изучим его в этом и последующих разделах. Во многих отношениях освоение Git является более сложной задачей, чем изучение конкретного генератора статичных сайтов, такого как Jekyll или Hugo. 4 | 5 | [Подключение к контролю версий](#plugging) 6 | 7 | [Различные типы систем контроля версий](#types) 8 | 9 | [Идея контроля версий](#idea) 10 | 11 | [Основной рабочий процесс в контроле версий](#workflow) 12 | 13 | [Ветвление](#branching) 14 | 15 | 16 | ## Подключение к контролю версий 17 | 18 | При работе с документацией API, потребуется подключение к системе контроля версий команды разработчиков, чтобы получить код. Или можно создавать ветки, чтобы добавлять или редактировать документацию там. 19 | 20 | Многие разработчики очень хорошо знакомы с системами версионирования, но, как правило, такие системы мало используются техническими писателями, потому что технические писатели традиционно работают с двоичными форматами файлов, такими как Microsoft Word и Adobe Framemaker. Бинарные форматы файлов доступны только для чтения на компьютерах, а системы контроля версий плохо справляются с управлением бинарными файлами, поскольку невозможно отследить изменения в разных версиях. 21 | 22 | Работая с форматами текстовых файлов, можно интегрировать рабочий процесс документации в систему управления версиями. При этом откроется целый новый мир! 23 | 24 | 25 | ## Различные типы систем контроля версий 26 | 27 | Существуют разные типы систем контроля версий. Централизованная система управления версиями требует, чтобы каждый пользователь проверял или синхронизировал файлы с центральным хранилищем при их редактировании. 28 | 29 | Чаще всего разработчики программного обеспечения используют *распределенные* системы контроля версий. Наиболее распространенная система - это Git (вероятно, потому что GitHub предоставляет Git-репозитории бесплатно в Интернете). Есть и другие системы управления версиями, например: Mercurial, Subversion (SVN) и Perforce. Из-за популярности Git, на нем мы и сосредоточимся. 30 | 31 | Git и GitHub - это две разные вещи. GitHub предоставляет онлайн-репозитории и инструменты для Git. GitHub - это платформа для управления проектами Git с приятным графическим интерфейсом для выполнения некоторых задач Git, таких например, как запросы на извлечение. 32 | 33 | ![github](pics/32.png) 34 | 35 | 36 | [Bitbucket](https://bitbucket.org/product) - это версия GitHub компании Altassian. Bitbucket позволяет использовать Git или Mercurial, но большинство проектов Bitbucket используют Git. 37 | 38 | 39 | ## Идея контроля версий 40 | 41 | После установки программного обеспечения для контроля версий, такого как Git, и инициализации репозитория на компьютере, в созданном репозитории добавляется невидимая папка. Эта невидимая папка управляет версиями содержимого этой папки. (При перемещении отслеживания Git в другую папку, невидимая папка git должна переноситься в ту же папку.) 42 | 43 | Добавляя файлы в Git и фиксируя их (создавая коммит), Git делает моментальный снимок зафиксированных файлов в этот момент времени. При фиксации другого изменения, Git создает еще один снимок. Если понадобиться вернуться к более ранней версии файла, нужно просто открыть определенный снимок. Такие снимки являются основной идеей создания версий контента. 44 | 45 | 46 | ## Основной рабочий процесс в контроле версий 47 | 48 | В Интернете есть много отличных учебников по управлению версиями, посмотрим эти учебники за более подробной информацией (например [GIT HOW TO](https://githowto.com/ru), у которого есть и версия на русском языке). Git предоставляет несколько этапов для файлов. Вот общий рабочий процесс: 49 | 50 | 1. Сначала добавляем все файлы, которые Git будет отслеживать. То, что файлы находятся в инициализированном репозитории Git, не означает, что Git фактически отслеживает и контролирует их изменения. Только когда файл официально «добавлен» в проект Git, Git начинает отслеживать изменения в этом файле. 51 | 2. Любые измененные файлы, которые отслеживает Git, находятся в «промежуточной» области. 52 | 3. При фиксации файла (создание коммита), Git создает моментальный снимок файла в этот момент времени, к которому можно всегда вернуться при дальнейшей работе. 53 | 4. После фиксации, изменения отправляются в мастер (Push). После внесения изменений в мастер, локальная копия и ветка мастер синхронизируются. 54 | 55 | 56 | ## Ветвление 57 | 58 | По умолчанию репозиторий Git является веткой master. При совместной работе с другими пользователями в рамках одного проекта обычно люди разветвляют основную ветку (master), вносят изменения в ветку, а затем объединяют (merge) ветку с веткой master. 59 | 60 | Редакция аннотации документов в файлах кода следует тому же рабочему процессу - вносить изменения в определенную ветку документов. После редактирования создается запрос (pull request), чтобы разработчики слили ветку doc обратно в master. 61 | 62 | После краткого введения в docs-as-code и контроль версий попробуем попрактиковаться, работая в Git: 63 | 64 | - [Практическое занятие: Управляем контентом в Wiki Github](Manage-wiki-content.md) 65 | - [Практическое занятие: Используем клиент GitHub для десктопа](Use-GitHub-Desktop.md) 66 | -------------------------------------------------------------------------------- /Publishing-doc/pics/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/1.png -------------------------------------------------------------------------------- /Publishing-doc/pics/10.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/10.jpg -------------------------------------------------------------------------------- /Publishing-doc/pics/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/10.png -------------------------------------------------------------------------------- /Publishing-doc/pics/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/12.png -------------------------------------------------------------------------------- /Publishing-doc/pics/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/13.png -------------------------------------------------------------------------------- /Publishing-doc/pics/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/14.png -------------------------------------------------------------------------------- /Publishing-doc/pics/15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/15.png -------------------------------------------------------------------------------- /Publishing-doc/pics/16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/16.png -------------------------------------------------------------------------------- /Publishing-doc/pics/17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/17.png -------------------------------------------------------------------------------- /Publishing-doc/pics/18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/18.png -------------------------------------------------------------------------------- /Publishing-doc/pics/19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/19.png -------------------------------------------------------------------------------- /Publishing-doc/pics/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/2.png -------------------------------------------------------------------------------- /Publishing-doc/pics/20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/20.png -------------------------------------------------------------------------------- /Publishing-doc/pics/21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/21.png -------------------------------------------------------------------------------- /Publishing-doc/pics/22.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/22.png -------------------------------------------------------------------------------- /Publishing-doc/pics/23.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/23.png -------------------------------------------------------------------------------- /Publishing-doc/pics/24.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/24.png -------------------------------------------------------------------------------- /Publishing-doc/pics/25.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/25.png -------------------------------------------------------------------------------- /Publishing-doc/pics/26.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/26.png -------------------------------------------------------------------------------- /Publishing-doc/pics/27.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/27.png -------------------------------------------------------------------------------- /Publishing-doc/pics/28.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/28.png -------------------------------------------------------------------------------- /Publishing-doc/pics/29.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/29.png -------------------------------------------------------------------------------- /Publishing-doc/pics/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/3.png -------------------------------------------------------------------------------- /Publishing-doc/pics/30.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/30.png -------------------------------------------------------------------------------- /Publishing-doc/pics/31.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/31.png -------------------------------------------------------------------------------- /Publishing-doc/pics/32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/32.png -------------------------------------------------------------------------------- /Publishing-doc/pics/33.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/33.png -------------------------------------------------------------------------------- /Publishing-doc/pics/34.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/34.png -------------------------------------------------------------------------------- /Publishing-doc/pics/35.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/35.png -------------------------------------------------------------------------------- /Publishing-doc/pics/36.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/36.png -------------------------------------------------------------------------------- /Publishing-doc/pics/37.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/37.png -------------------------------------------------------------------------------- /Publishing-doc/pics/38.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/38.png -------------------------------------------------------------------------------- /Publishing-doc/pics/39.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/39.png -------------------------------------------------------------------------------- /Publishing-doc/pics/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/4.png -------------------------------------------------------------------------------- /Publishing-doc/pics/40.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/40.png -------------------------------------------------------------------------------- /Publishing-doc/pics/41.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/41.png -------------------------------------------------------------------------------- /Publishing-doc/pics/42.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/42.png -------------------------------------------------------------------------------- /Publishing-doc/pics/43.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/43.png -------------------------------------------------------------------------------- /Publishing-doc/pics/44.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/44.png -------------------------------------------------------------------------------- /Publishing-doc/pics/45.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/45.png -------------------------------------------------------------------------------- /Publishing-doc/pics/46.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/46.png -------------------------------------------------------------------------------- /Publishing-doc/pics/47.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/47.png -------------------------------------------------------------------------------- /Publishing-doc/pics/48.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/48.png -------------------------------------------------------------------------------- /Publishing-doc/pics/49.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/49.png -------------------------------------------------------------------------------- /Publishing-doc/pics/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/5.png -------------------------------------------------------------------------------- /Publishing-doc/pics/50.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/50.png -------------------------------------------------------------------------------- /Publishing-doc/pics/51.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/51.png -------------------------------------------------------------------------------- /Publishing-doc/pics/52.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/52.png -------------------------------------------------------------------------------- /Publishing-doc/pics/53.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/53.png -------------------------------------------------------------------------------- /Publishing-doc/pics/54.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/54.png -------------------------------------------------------------------------------- /Publishing-doc/pics/55.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/55.png -------------------------------------------------------------------------------- /Publishing-doc/pics/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/6.png -------------------------------------------------------------------------------- /Publishing-doc/pics/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/7.png -------------------------------------------------------------------------------- /Publishing-doc/pics/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/8.png -------------------------------------------------------------------------------- /Publishing-doc/pics/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/Publishing-doc/pics/9.png -------------------------------------------------------------------------------- /conceptual-topics/API-overview.md: -------------------------------------------------------------------------------- 1 | # Обзор API 2 | 3 | В обзоре API объясняется, что можно делать при помощи API (включая бизнес-цели высокого уровня, потребности рынка или болевые точки, которые он решает), для кого предназначен API. Обзор может содержать и другую вводную информацию. 4 | 5 | #### Содержание раздела 6 | 7 | [Цель обзора API](#purpose) 8 | 9 | [Пояснение проблем рынка, которые решает API](#marketProblems) 10 | 11 | [Примеры обзора API](#samples) 12 | 13 | - [SendGrid](#SendGrid) 14 | 15 | - [Lyft](#Lyft) 16 | 17 | - [IBM Watson Assistant](#IBM) 18 | 19 | [Практическое занятие с обзором API](#activity) 20 | 21 | 22 | ## Цель обзора API 23 | 24 | Слишком часто (возможно, потому что контент часто пишется разработчиками) API документация быстро теряется в технических деталях, даже не объясняя четко, для чего используется этот API. Не стоит забывать об общей цели и бизнес-целях API, распаляясь на конечные точки. 25 | 26 | Обзор API предоставляет пользователям верхнеуровневое понимание системы. Такое понимание имеет решающее значение для того, чтобы охватить систему в целом, позволяет деталям вписываться в более широкие концептуальные рамки. 27 | 28 | Чтобы получить представление о том, что такое API, пользователи начинают с верхнего уровня, получают представление, о чем идет речь из заголовка и описания, а затем переходят к более подробной информации. такой обзор предоставляет начальную ориентацию для пользователя. 29 | 30 | ![high-level](img/1.jpg) 31 | > В обзоре API объясняется, что можно делать при помощи API (включая бизнес-цели высокого уровня, потребности рынка или болевые точки, которые он решает), для кого предназначен API 32 | 33 | Для получения дополнительной информации о важности общих обзоров см. [Reduction, layering, and distillation as a strategy for simplicity](https://idratherbewriting.com/simplifying-complexity/reduction-layering-distillation.html). 34 | 35 | В обзоре перечисляются распространенные бизнес-сценарии, в которых может быть полезен API. Эти сценарии предоставляют пользователям контекст, в котором они нуждаются, чтобы оценить, соответствует ли API их потребностям. 36 | 37 | Имейте в виду, есть тысячи API. Если люди просматривают ваш API, их первый и самый неотложный вопрос: "какую информацию он возвращает? Является ли эта информация актуальной и полезной для моих нужд?"" 38 | 39 | 40 | ## Пояснение проблем рынка, которые решает API 41 | 42 | В статье [20 основных причинах неудачи стартапов](https://www.cbinsights.com/research/startup-failure-reasons-top/) одной из главных причин неудач стартапов является их неспособность решить рыночную проблему. Авторы объясняют: 43 | 44 | > Стартапы терпят неудачу, когда они не решают проблему рынка. Мы не решали достаточно большую проблему, которую мы могли бы универсально обслуживать с помощью масштабируемого решения. У нас были отличные технологии, отличные данные о покупательском поведении, отличная репутация лидера, большой опыт, отличные консультанты и т.д., Но у нас не было технологии или бизнес-модели, которая решала бы проблему масштабируемым образом. (CB Insights) 45 | 46 | Этот обзор посвящен проблеме рынка, которую решает API. Если API не работает, скорее всего, это из-за того, что он не решает проблему рынка. 47 | 48 | Обзор API обычно размещается на главной странице API. Домашняя страница (начало документации) является хорошим местом для размещения такого обзора, потому что в таком обзоре также определяется и своя аудитория. Понимание аудитории поможет правильно сориентировать контент в документации по API. 49 | 50 | 51 | ## Примеры обзора API 52 | 53 | Приведем несколько примеров обзоров API: 54 | 55 | 56 | ### SendGrid 57 | 58 | ![SendGrid](img/2.png) 59 | 60 | Обзор Sendgrid начинается с двух ключевых разделов: «Что такое SendGrid?» И «Для кого SendGrid?». Отличный простой подход. Даже в описании того, что такое SendGrid, авторы не предполагают, что все знают, что такое SMTP-провайдер, поэтому разместили ссылку на дополнительную информацию. В целом, примерно за 10 секунд можно получить представление о том, что такое API SendGrid. 61 | 62 | 63 | ### Lyft 64 | 65 | ![Lyft](img/3.png) 66 | 67 | Обзор API Lyft начинается аналогичным образом, с разделов «Что такое Lyft?» И «Зачем использовать Lyft в качестве разработчика». Их домашняя страница также предоставляет информацию о доступе, ограничениях скорости и регулировании, а также тестировании. Авторы Lyft также признают, что у каждого домена технологий есть свой собственный жаргон, поэтому они заранее предоставляют [глоссарий](api-glossary.md). 68 | 69 | 70 | ### IBM Watson Assistant 71 | 72 | ![IBM Watson Assistant](img/4.png) 73 | 74 | IBM Watson Assistant начинается с краткого описания сервиса, после чего следует общая схема системы и сводная информация о том, как ее реализовать. Включение диаграммы API дает пользователям хорошее представление о том, чего ожидать, например, об уровне сложности и времени, которое потребуется для внедрения API. 75 | 76 | 77 | ## 👨‍💻 Практическое занятие с обзором API 78 | 79 | В своем [найденном опен-сорс проекте](../documenting-api-endpoints/find-open-source-project.md) найдем раздел Обзор API и ответим на следующие вопросы: 80 | 81 | 1. Есть раздел **Обзор API** в документации? 82 | 2. Объясняет ли обзор, для кого предназначен API? 83 | 3. Обозначает ли обзор потребность рынка или бизнес-проблему, которую решает API? 84 | 4. Какие вопросы у вас остались об API после прочтения обзора? 85 | 5. Как обзор переходит к разделу **Начало работы** или другим первым шагам с API? 86 | 87 | [🔙](user-guide-topics.md) 88 | 89 | [Go next ➡](getting-started.md) 90 | -------------------------------------------------------------------------------- /conceptual-topics/README.md: -------------------------------------------------------------------------------- 1 | # Концептуальные темы API 2 | 3 | В то время как адресные темы в API, как правило, заслуживают наибольшее внимание, общим, концептуальным разделам, таким как разделы о начале работы, информация об авторизации, ограничении скорости, кодах состояния и ошибок, кратких справочных руководствах и других темах, уделяется около половины документации. 4 | 5 | Такими разделами обычно занимаются технические писатели, а не разработчики. 6 | 7 | Оценить качество документации API можно, посмотрев включает ли она такие безадресные темы. 8 | 9 | # Содержание модуля "Концептуальные разделы" 10 | 11 | [**Разделы руководства пользователя**](user-guide-topics.md) 12 | 13 | [**Обзор API**](API-overview.md) 14 | 15 | [**Руководство по началу работы**](getting-started.md) 16 | 17 | [**Требования аутентификации и авторизации**](authentication-and-authorization.md) 18 | 19 | [**Коды статусов и ошибок**](status-error-codes.md) 20 | 21 | [**Ограничения скорости**](rate-limiting.md) 22 | 23 | [**Описание и образцы кода**](code-samples.md) 24 | 25 | [**SDK и пример приложений**](sdks-sample-apps.md) 26 | 27 | [**Краткое справочное руководство**](quick-reference-guide.md) 28 | 29 | [**API Глоссарий**](api-glossary.md) 30 | 31 | [**Лучшие практики API**](best-practices.md) 32 | 33 | [**Практическое занятие: Оценка концептуального контента в проекте**](assess-conceptual-content.md) 34 | 35 | [🔙](testing-api-doc/test-documentation.md) 36 | 37 | [Go next ➡](user-guide-topics.md) 38 | -------------------------------------------------------------------------------- /conceptual-topics/assess-conceptual-content.md: -------------------------------------------------------------------------------- 1 | # Практическое занятие: Оценка концептуального контента в проекте 2 | 3 | Каждую концептуальную тему этого модуля мы анализировали в контексте [выбранного опен-сорс проекта](../documenting-api-endpoints/find-open-source-project.md). Теперь расширим свой анализ, чтобы увидеть, как безадресные темы отображены на других сайтах документации API. Помните, что иногда лучший способ научиться создавать документацию API - это внимательно наблюдать за тем, как это делается на сайтах, которыми вы восхищаетесь. Следуя стандартным практикам в отрасли, можно создавать более предсказуемые и понятные шаблоны в собственной документации. 4 | 5 | ## 👨‍💻 Оценка концептуального контента 3 сайтов API документации 6 | 7 | 1. Переходим к [Списку 100 сайтов API документации](../Publishing-doc/API-doc-sites-list.md) и выбираем 3 сайта для анализа. Можно взять сайты любимых инструментов или любимых компаний, или просто 3 рандомных сайта. 8 | 9 | 2. Смотрим документацию и анализируем ее состав: 10 | 11 | | Безадресные разделы | Сайт 1 | Сайт 2 | Сайт 3 | 12 | |:--|:--|:--|:--| 13 | | [Обзор API](API-overview.md) |||| 14 | | [Начало работы](getting-started.md) |||| 15 | | [Аутентификация и авторизация](authentication-and-authorization.md) |||| 16 | | [Коды сатусов и ошибок](status-error-codes.md) |||| 17 | | [Ограничения скорости](rate-limiting.md)|||| 18 | | [Примеры кода и руководства](code-samples.md) |||| 19 | | [SDK и примеры приложений](sdks-sample-apps.md)|||| 20 | | [Краткое справочное руководство](quick-reference-guide.md) |||| 21 | |[API глоссарий](api-glossary.md) |||| 22 | | [Лучшие практики](best-practices.md) |||| 23 | 24 | Создаем такую таблицу в своем любимом текстовом редакторе и заполняем по возможности все столбцы. 25 | 26 | 3. Появились какие-либо заслуживающие внимания наблюдения из анализа? 27 | 28 | [🔙](best-practices.md) 29 | 30 | [Go next ➡](../Publishing-doc/README.md) 31 | -------------------------------------------------------------------------------- /conceptual-topics/best-practices.md: -------------------------------------------------------------------------------- 1 | # Лучшие практики (Best practices) API 2 | 3 | Лучшие практики API могут быть любыми советами, которые ваша команда разработчиков хочет сообщить разработчикам о работе с API. Нет определенного количества тем, которые обычно рассматриваются в передовых методах API. Вместо этого, лучшие практики могут быть общим заголовком для контента, который нигде не подходит. 4 | 5 | [Какие темы включать в Best practices](#topics) 6 | 7 | [Примеры Best practices](#samples) 8 | 9 | - [Mailchimp](#mailchimp) 10 | 11 | - [Coinbase](#coinbase) 12 | 13 | [Практическое занятие: Best practices](#activity) 14 | 15 | 16 | ## Какие темы включать в Best practices 17 | 18 | Хотя многие из тем в документации API являются стандартными, обычно есть подробный список вещей, которые нужно знать о работе с API. Такую информацию можно получить только по запросу разработчиков. 19 | 20 | Список тем может включать такие темы, как: 21 | 22 | - разбиение на страницы, 23 | - временные диапазоны, 24 | - отказоустойчивость, 25 | - значения кэша, 26 | - возможности подключения, 27 | - тайм-ауты, 28 | - время простоя, 29 | - SSL, 30 | - версии, 31 | - тестирование и проверка, 32 | - экспорты, 33 | - языки, 34 | - обработка номеров, 35 | - расширение ресурсов, 36 | - уведомления, 37 | - CORS., 38 | - локализация 39 | 40 | и многое другое. 41 | 42 | ![bestPracticies](img/58.jpg) 43 | > Best practices охватывают ряд тем, обычно уникальных для вашего API 44 | 45 | 46 | ## Примеры Best practices 47 | 48 | Ниже приведены примеры Best practices по использованию API с нескольких сайтов документации по API. 49 | 50 | 51 | ### Mailchimp 52 | 53 | ![Mailchimp](img/59.png) 54 | > Best practices Mailchimp 55 | 56 | Best practices Mailchimp API включают советы по отказоустойчивости, использованию конкретных запросов, аутентификации, значениям кэша, подключению и регистрации. Благодаря отказоустойчивости Mailchimp напоминает разработчикам о том, что иногда случаются простои, поэтому они должны планировать соответствующую обработку сценариев, если API не отвечает. С помощью специальных запросов Mailchimp предупреждает пользователей о времени, которое может потребоваться, если запрос слишком общий, и, следовательно, возвращает слишком много информации. 57 | 58 | 59 | ### Coinbase 60 | 61 | ![Coinbase](img/60.png) 62 | > Best practices Coimbase 63 | 64 | Coinbase не ссылается на такие темы как лучшие практики; вместо этого навигационная панель показывает список тем. Пагинация - одна из этих тем, на которой стоит остановиться. Как нумерация страниц связана с API? Предположим, что конечная точка API возвращает все элементы в учетной записи пользователя. Может быть тысячи элементов, и если все элементы были возвращены в одном ответе, API может потребоваться много времени для сбора и возврата большого количества данных. В результате, как и при поиске в Google, ответ возвращает ограниченный набор, например первые десять элементов, а затем содержит URL-адрес, который можно использовать для перехода к следующему набору ответов. Разбиение на страницы относится к переходу на следующую страницу ответов. 65 | 66 | 67 | Ранее, определяя характеристики REST, упоминалась [HATEOS](../introduction-rest-apis/what-is-rest-api.md#cash) или «Гипермедиа как движок состояния приложения». Ссылки в ответах, которые возвращают больше результатов, являются одним из примеров HATEOS. 68 | 69 | Программная обработка URL-адреса для получения большего количества ответов может быть довольно сложной задачей. Если нужно, чтобы все элементы были возвращены, а затем отфильтрованы и отсортированы, найдя конкретные значения для извлечения, как бы вы сделали это, используя URL-адрес, возвращенный в ответе? Команда может дать совет разработчикам, работающим с этими сценариями. Скорее всего, конечная точка будет предлагать фильтры в качестве параметров для применения к конечной точке, чтобы первоначальный ответ содержал требуемый набор элементов. Такой вид совета может быть уместен в лучших методиках API. 70 | 71 | 72 | ## 👨‍💻 Практическое занятие: Best practices 73 | 74 | В своем [найденном опен-сорс проекте](../documenting-api-endpoints/find-open-source-project.md) найдем раздел Best practices. Ответим на вопросы: 75 | 76 | 1. Существуют ли Best practices для работы с API, которые не вписываются ни в какие другие типичные темы API? 77 | 2. Как организованы Best practices в существующей документации? Они перечислены в FAQ? 78 | 3. Какие актуальные темы рассматриваются в Best practices? 79 | 4. Есть ли в проекте проблемы, которые должны быть отражены в Best practices API? 80 | 81 | [🔙](api-glossary.md) 82 | 83 | [Go next ➡](assess-conceptual-content.md) 84 | -------------------------------------------------------------------------------- /conceptual-topics/img/1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/1.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/10.png -------------------------------------------------------------------------------- /conceptual-topics/img/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/11.png -------------------------------------------------------------------------------- /conceptual-topics/img/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/12.png -------------------------------------------------------------------------------- /conceptual-topics/img/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/13.png -------------------------------------------------------------------------------- /conceptual-topics/img/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/14.png -------------------------------------------------------------------------------- /conceptual-topics/img/15.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/15.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/16.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/16.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/17.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/17.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/18.png -------------------------------------------------------------------------------- /conceptual-topics/img/19.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/19.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/2.png -------------------------------------------------------------------------------- /conceptual-topics/img/20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/20.png -------------------------------------------------------------------------------- /conceptual-topics/img/21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/21.png -------------------------------------------------------------------------------- /conceptual-topics/img/22.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/22.png -------------------------------------------------------------------------------- /conceptual-topics/img/23.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/23.png -------------------------------------------------------------------------------- /conceptual-topics/img/24.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/24.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/25.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/25.png -------------------------------------------------------------------------------- /conceptual-topics/img/26.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/26.png -------------------------------------------------------------------------------- /conceptual-topics/img/27.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/27.png -------------------------------------------------------------------------------- /conceptual-topics/img/28.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/28.png -------------------------------------------------------------------------------- /conceptual-topics/img/29.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/29.png -------------------------------------------------------------------------------- /conceptual-topics/img/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/3.png -------------------------------------------------------------------------------- /conceptual-topics/img/30.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/30.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/31.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/31.png -------------------------------------------------------------------------------- /conceptual-topics/img/32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/32.png -------------------------------------------------------------------------------- /conceptual-topics/img/33.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/33.png -------------------------------------------------------------------------------- /conceptual-topics/img/34.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/34.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/35.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/35.png -------------------------------------------------------------------------------- /conceptual-topics/img/36.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/36.png -------------------------------------------------------------------------------- /conceptual-topics/img/37.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/37.png -------------------------------------------------------------------------------- /conceptual-topics/img/38.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/38.png -------------------------------------------------------------------------------- /conceptual-topics/img/39.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/39.png -------------------------------------------------------------------------------- /conceptual-topics/img/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/4.png -------------------------------------------------------------------------------- /conceptual-topics/img/40.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/40.png -------------------------------------------------------------------------------- /conceptual-topics/img/41.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/41.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/42.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/42.png -------------------------------------------------------------------------------- /conceptual-topics/img/43.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/43.png -------------------------------------------------------------------------------- /conceptual-topics/img/44.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/44.png -------------------------------------------------------------------------------- /conceptual-topics/img/45.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/45.png -------------------------------------------------------------------------------- /conceptual-topics/img/46.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/46.png -------------------------------------------------------------------------------- /conceptual-topics/img/47.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/47.png -------------------------------------------------------------------------------- /conceptual-topics/img/48.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/48.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/49.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/49.png -------------------------------------------------------------------------------- /conceptual-topics/img/5.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/5.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/50.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/50.png -------------------------------------------------------------------------------- /conceptual-topics/img/51.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/51.png -------------------------------------------------------------------------------- /conceptual-topics/img/52.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/52.png -------------------------------------------------------------------------------- /conceptual-topics/img/53.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/53.png -------------------------------------------------------------------------------- /conceptual-topics/img/54.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/54.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/55.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/55.png -------------------------------------------------------------------------------- /conceptual-topics/img/56.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/56.png -------------------------------------------------------------------------------- /conceptual-topics/img/57.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/57.png -------------------------------------------------------------------------------- /conceptual-topics/img/58.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/58.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/59.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/59.png -------------------------------------------------------------------------------- /conceptual-topics/img/6.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/6.jpg -------------------------------------------------------------------------------- /conceptual-topics/img/60.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/60.png -------------------------------------------------------------------------------- /conceptual-topics/img/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/7.png -------------------------------------------------------------------------------- /conceptual-topics/img/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/8.png -------------------------------------------------------------------------------- /conceptual-topics/img/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/conceptual-topics/img/9.png -------------------------------------------------------------------------------- /conceptual-topics/rate-limiting.md: -------------------------------------------------------------------------------- 1 | # Ограничения скорости 2 | 3 | Ограничения скорости определяют, как часто можно осуществлять запросы по конкретной конечной точке. Обычно компании имеют разные уровни (например, бесплатные и профессиональные) и лицензии (с открытым исходным кодом, бизнес, коммерческие), соответствующие различным возможностям или ограничениям скорости API. 4 | 5 | [Что покрывать при помощи ограничения скорости](#cover) 6 | 7 | [Пример разделов "Ограничения скорости"](#examples) 8 | 9 | - [GitHub](#github) 10 | 11 | - [Linkedin](#linkedin) 12 | 13 | - [Bitly](#bitly) 14 | 15 | [Практическое занятие: Ограничения скорости](#activity) 16 | 17 | 18 | ## Что покрывать при помощи ограничения скорости 19 | 20 | Компании, имеющие API зарабатывают деньги, взимая плату за доступ к API. Обычно различают низкое и высокое использование, часто освобождая варианты с низким использованием, чтобы разработчики могли исследовать и экспериментировать с API. На примере [API OpenWeatherMap Weather](https://openweathermap.org/price), который мы используем на этом курсе, можно увидеть, где начинается уровень ценообразования: 21 | 22 | ![OpenWeatherMap](img/29.png) 23 | > Уровни ценообразования для API OpenWeatherMap. Каждый вызов - это запрос к API. Если на странице отображается только один запрос о погоде, и приходит более 60 посетителей в секунду, необходимо пройти мимо бесплатного уровня пользования. 24 | 25 | Если сайт посещает сотни тысяч человек в день и каждая перезагрузка страницы дергает конечную точку API, нужно быть уверенным, что API может поддерживать такой тип трафика. 26 | 27 | Ценообразование, относящееся к ограничениям скорости, - это, вероятно, информация, которая находится в области маркетинга, а не в области документации. Тем не менее, разработчикам стоит знать ключевые варианты поведения, включающие пороги ограничения скорости. Например: 28 | 29 | - Замедляется ли получение ответов при превышении порога скорости? 30 | - Приходится ли платить за каждый дополнительный запрос? 31 | - Возвращает ли ответ определенный код состояния при превышении порога скорости (если да, то какой?) 32 | 33 | 34 | Как разработчики обрабатывают ситуации, если, при внедрении кода в приложения, API не отвечает из-за нарушений ограничения скорости? Существуют ли условия и проверки для обработки таких сценариев с ограничениями? Может зависать виджет (или что-то еще, что может реализовывать API), или будет отображаться пустым, или будет происходит сбой? 35 | 36 | ![threshold](img/30.jpg) 37 | > Ограничение скорости может показаться маркетинговой темой, но политики ограничения скорости и их влияние на вызовы API могут оказать существенное влияние на разработку. 38 | 39 | 40 | ## Пример разделов "Ограничения скорости" 41 | 42 | Ниже приведены несколько примеров с разделами "Ограничения скорости" в API 43 | 44 | 45 | ### GitHub 46 | 47 | ![Github](img/31.png) 48 | > Ограничения скорости GitHub 49 | 50 | Документация GitHub объясняет: 51 | 52 | - ограничения скорости для аутентифицированных и не аутентифицированных запросов, которые возвращает заголовок, 53 | - значение ограничивающих скорость заголовков (`X-RateLimit-Limit`, `X-RateLimit-Remaining` и `X-RateLimit-Reset`), 54 | - как проверить текущее использование, 55 | - как увеличить лимиты скорости для конкретного приложения, 56 | - что происходит при злоупотреблении лимитами и многое другое. 57 | 58 | 59 | ### Linkedin 60 | 61 | ![LinkedIn](img/32.png) 62 | > Ограничения скорости LinkedIn 63 | 64 | Документация Linkedin по ограничению скорости объясняет, что разные конечные точки API имеют разные ограничения. Существует три различных типа регулирования: 65 | 66 | - регулирование приложений, 67 | - регулирование пользователей; 68 | - регулирование разработчиков. 69 | 70 | Их документация также объясняет часовой пояс, используемый для отслеживания начала и конца дня. 71 | 72 | 73 | ### Bitly 74 | 75 | ![bitly](img/33.png) 76 | 77 | Bitly предоставляет основную информацию на странице выше, а также [ссылки на лучшие практики для избегания проблем с ограничением скорости](https://dev.bitly.com/best_practices.html). Эти передовые практики включают советы о кэшировании, проблемах безопасности, длинных загрузок страниц, пакетной обработке, запросах большого объема, кодирования URL и многое другое. 78 | 79 | Глядя на примеры, можно увидеть, что, хотя ограничение скорости может показаться простой темой, существуют уровни глубины и сложности, которые необходимо охватить. Актуальность темы зависит от нашего API и политики ограничений, установленных вашей компанией, но эта информация не может быть полностью загружена в маркетинг для обработки. Большая часть информации об ограничении скорости напрямую влияет на развитие. 80 | 81 | 82 | ## 👨‍💻 Практическое занятие: Ограничения скорости 83 | 84 | В своем [найденном опен-сорс проекте](../documenting-api-endpoints/find-open-source-project.md) найдем информацию об ограничениях в API документации. Ответим на следующие вопросы: 85 | 86 | 1. Есть ли у API ограничения? 87 | 2. Что произойдет в результате превышения ограничений? 88 | 3. Какой код статуса появится при превышении ограничений? 89 | 4. Какие ограничения скорости существуют для свободных (или разрабатываемых) уровней API? 90 | 91 | [🔙](status-error-codes.md) 92 | 93 | [Go next ➡](code-samples.md) 94 | -------------------------------------------------------------------------------- /conceptual-topics/user-guide-topics.md: -------------------------------------------------------------------------------- 1 | # Обзор концептуальных тем 2 | 3 | До этого момента мы в основном фокусировались на [справочных аспектах документации API](../documenting-api-endpoints/README.md) (конечные точки). Адресная документация - это только один аспект документации API. В этом разделе поговорим о концептуальных разделах, которые обычно встречаются в документации API. Вместо понятия «концептуальные разделы» можно принимать эту информацию в качестве «руководства пользователя». 4 | 5 | #### Содержание раздела 6 | 7 | [Разделы руководства пользователя](#topics) 8 | 9 | 10 | ## Разделы руководства пользователя 11 | 12 | Ниже приведены концептуальные разделы, обычно встречающиеся в документации API: 13 | 14 | - [Обзор API](API-overview.md) 15 | - [Начало работы](getting-started.md) 16 | - [Требования аутентификации и авторизации](authentication-and-authorization.md) 17 | - [Коды статусов и ошибок](status-error-codes.md) 18 | - [Ограничения скорости](rate-limiting.md) 19 | - [Описание и примеры кода](code-samples.md) 20 | - [SDK и пример приложений](sdks-sample-apps.md) 21 | - [Краткое справочное руководство](quick-reference-guide.md) 22 | - [API Глоссарий](api-glossary.md) 23 | - [Лучшие практики API](best-practices.md) 24 | 25 | Помимо этих разделов, можно добавлять и другие задачи и пособия, относящиеся к API, исходя из того, что ожидается от пользователей, и бизнес-сценариев, для которых они будут использовать API. 26 | 27 | В каждом безадресном разделе будут приведены общие описания и обзоры содержания этих разделов, а также примеры с реальных сайтов документации API. 28 | 29 | В своем [найденном опен-сорс проекте](../documenting-api-endpoints/find-open-source-project.md) можно пройти по каждому концептуальному разделу и оценить его. Хотя многие из понятий в разделе являются базовыми, при рассмотрении информации в контексте, то есть, как на самом деле реализована информация, все становится намного интереснее. 30 | 31 | [🔙](README.md) 32 | 33 | [Go next ➡](API-overview.md) 34 | -------------------------------------------------------------------------------- /doc-code/README.md: -------------------------------------------------------------------------------- 1 | # Документирование когда 2 | 3 | Данный раздел находится в разработке автором оригинального курса, перевод по мере пополнения контента и наличия времени переводчика 🖍 4 | 5 | ## Содержание модуля "Документирование когда" 6 | 7 | [**Почему документирование кода так сложно?**](doc-code.md) 8 | 9 | [**Исследования о документировании кода**](doc-research.md) 10 | 11 | [**Пять стратегий документирования кода**](doc-strategy.md) 12 | 13 | [🔙](../glossary-and-resourses/answeres-whats-wrong.md) 14 | 15 | [Go next ➡](doc-code.md) 16 | -------------------------------------------------------------------------------- /doc-code/doc-research.md: -------------------------------------------------------------------------------- 1 | # Исследования о документировании кода 2 | 3 | Прежде чем изучать, как документировать код, давайте сначала рассмотрим некоторые исследования, которые были проведены по передовым методам документирования кода, так как это может определить наше направление и подход. 4 | 5 | Несколько академических статей выделяются как заслуживающие внимания: 6 | 7 | - **Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++** 8 | 9 | В этой статье рассказывается, как разработчики из Google находят и используют документацию кода. Исследователи обнаружили, что простой код иногда разработчики предпочитают исследовать напрямую. Однако для более сложного кода разработчики обращаются к документации кода, часто просматривая формальные объявления классов для получения нужной информации. В других случаях они смотрят на комментарии в коде реализации. Помимо предоставления руководства по наилучшему расположению документации, исследователи также определяют, какой тип ответов и рекомендации разработчики хотят получить в документации. 10 | 11 | - **Как разработчики используют документацию API: изучение наблюдений** 12 | 13 | В этой статье исследователи смотрели на то, как разработчики взаимодействуют с документацией API, и обнаружили сочетание как систематического (сначала читайте, изучайте позже), так и оппортунистического (изучайте сначала, читайте позже) стилей обучения. Хотя мы часто пишем систематически, сосредоточение внимания на оппортунистическом поведении может быть более полезным, что побудит нас более внимательно следить за улучшением поиска, навигации, интерактивных компонентов, устранения неполадок, сообщений об ошибках и других функций, ориентированных на действия. 14 | 15 | Обе эти статьи взяты из научных журналов. На самом деле редко можно найти исследования о документации API в академических журналах (не знаю почему), и когда вы их находите, они часто бывают в инженерных журналах, или журналах по информатике (а не в журналах по техническим коммуникациям). 16 | 17 | [Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++](#no-comments) 18 | 19 | - [Тип кода, которому нужна документация](#type-of-code) 20 | - [Когда документировать код](#time-to-document) 21 | - [Вопросы, решаемые в документации кода](#questions) 22 | - [Заключение](#conclusion-one) 23 | 24 | [Как разработчики используют документацию API: изучение наблюдений](#use-api-doc) 25 | 26 | - [Систематическое поведение против оппортунистического](#sys-versus-opp) 27 | - [Проектирование для оппортунистического поведения](#design) 28 | - [Временные затраты пользователей](#time) 29 | - [Заключение](#conclusion-two) 30 | 31 | [Выводы исследований](#takeaways) 32 | 33 | 34 | 35 | 36 | 37 | ## Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++ 38 | 39 | 40 | ### Тип кода, которому нужна документация 41 | 42 | 43 | ### Когда документировать код 44 | 45 | 46 | ### Вопросы, решаемые в документации кода 47 | 48 | 49 | ### Заключение 50 | 51 | 52 | ## Как разработчики используют документацию API: изучение наблюдений 53 | 54 | 55 | ### Систематическое поведение против оппортунистического 56 | 57 | 58 | ### Проектирование для оппортунистического поведения 59 | 60 | 61 | ### Временные затраты пользователей 62 | 63 | 64 | ### Заключение 65 | 66 | 67 | ## Выводы исследований 68 | -------------------------------------------------------------------------------- /doc-code/doc-strategy.md: -------------------------------------------------------------------------------- 1 | # Пять стратегий документирования кода 2 | 3 | 4 | В этом разделе мы рассмотрим подходы к фактическому документированию кода. Здесь есть несколько подходов, которые используют авторы и инженеры, и я рассмотрел пять из них с примерами и комментариями. 5 | -------------------------------------------------------------------------------- /doc-code/img/1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/doc-code/img/1.jpg -------------------------------------------------------------------------------- /documenting-api-endpoints/README.md: -------------------------------------------------------------------------------- 1 | # Документирование конечных точек 2 | 3 | Документация ссылки конечной точки API состоит из пяти основных разделов: 4 | 5 | - описания ресурсов; 6 | - конечные точки и методы; 7 | - параметры; 8 | - примеры запросов; 9 | - примеры ответов и схем. 10 | 11 | Чтобы задокументировать идеальные конечные точки API, старайтесь предоставлять подробную информацию для каждого из этих разделов. 12 | 13 | # Содержание модуля "Документирование конечных точек" 14 | 15 | [**Документирование новой конечной точки**](new-endpoint.md) 16 | 17 | [**Обзор пошагового описания API ссылки**](api-reference-tutorial-overview.md) 18 | 19 | [**Шаг 1: Описание ресурса**](step1-resourse-description.md) 20 | 21 | [**Шаг 2: Конечные точки и методы**](step2-endpoints-and-methods.md) 22 | 23 | [**Шаг 3: Параметры**](step3-parameters.md) 24 | 25 | [**Шаг 4: Пример запроса**](step4-request-example.md) 26 | 27 | [**Шаг 5: Пример и схема ответа**](step5-response-example-and-schema.md) 28 | 29 | [**Собираем все вместе**](putt-all-together.md) 30 | 31 | [**Практическое занятие: Что не так в разделе API?**](whats-wrong.md) 32 | 33 | [**Практическое занятие: Поиск open-source проекта**](find-open-source-project.md) 34 | 35 | [**Практическое занятие: Оценка ключевых элементов API документации**](evaluate-api-referense-docs.md) 36 | 37 | [🔙](../like-developer/dot-notation.md) 38 | 39 | [Go next ➡](new-endpoint.md) 40 | -------------------------------------------------------------------------------- /documenting-api-endpoints/api-reference-tutorial-overview.md: -------------------------------------------------------------------------------- 1 | # Обзор пошагового описания API ссылки 2 | 3 | В это обзоре мы поработаем над созданием 5 общих разделов документации API ссылки: 4 | 5 | - описание ресурса; 6 | - конечные точки и методы; 7 | - параметры; 8 | - примеры запроса; 9 | - примеры и схема ответа 10 | 11 | Чтобы обеспечить некоторый контекст (и продолжить наш пример сценария документации), мы разберем информацию из раздела [Документирование новой конечной точки](new-endpoint.md#wikiSerf) по этим пяти разделам. 12 | 13 | [5 Общих разделов в документации API](#commonSection) 14 | 15 | [Карта рабочего процесса описания](#map) 16 | 17 | [После описания](#afterTutorial) 18 | 19 | [Дальнейшие шаги](#nextSteps) 20 | 21 | 22 | ## 5 Общих разделов в документации API 23 | 24 | Почти все API содержат описание пяти разделов: 25 | 26 | [1. Описание ресурса](step1-resourse-description.md) 27 | 28 | В данном случае «Ресурсы» относятся к информации, возвращаемой API. 29 | 30 | [2. Конечные точки и методы](step2-endpoints-and-methods.md) 31 | 32 | Конечные точки указывают, как получить доступ к ресурсу, а метод указывает разрешенные взаимодействия (такие как GET, POST или DELETE) с ресурсом. 33 | 34 | [3. Параметры](step3-parameters.md) 35 | 36 | Параметрами являются данные, которые можно передать конечной точке (например, указать формат ответа или возвращаемую сумму), чтобы повлиять на ответ. 37 | 38 | [4. Пример запроса](step4-request-example.md) 39 | 40 | Пример запроса включает в себя простой пример использования конечной точки, показывающий какие-то настроенные параметры. 41 | 42 | [5. Пример и схема ответа](step5-response-example-and-schema.md) 43 | 44 | Пример ответа показывает простой пример ответа из примера запроса; Схема ответа определяет все возможные элементы в ответе. 45 | 46 | 47 | ## Карта рабочего процесса описания 48 | 49 | Ниже наскоро сделанная карта рабочего процесса, чтобы помочь сориентироваться на каждом шаге. 50 | 51 | | [Шаг 1. Описание ресурса](step1-resourse-description.md) |-->| [Шаг 2. Конечные точки и методы](step2-endpoints-and-methods.md) |-->| [Шаг 3. Параметры](step3-parameters.md) |-->| [Шаг 4. Пример запроса](step4-request-example.md)|-->| [Шаг 5. Пример и схема ответа](step5-response-example-and-schema.md) | 52 | 53 | 54 | ## После описания 55 | 56 | Когда мы закончим, конечный результат будет выглядеть как настоящее описание раздела API (см. Готовый результат в разделе [Собираем все вместе](putt-all-together.md)). На практических занятиях у нас будет возможность [редактировать или создавать описание API](evaluate-api-referense-docs.md) в выбранном [опен-сорс проекте](find-open-source-project.md). 57 | 58 | > Хотя существуют автоматические способы публикации документации API, в этой главе мы сосредоточимся на содержании, а не на инструментах. В следующем модуле, [Спецификация OpenAPI и Swagger](../openAPI-specification/README.md), мы рассмотрим, как описать те же самые компоненты, используя спецификацию OpenAPI. В модуле [Публикация документации по API](../Publishing-doc/README.md) мы рассмотрим способы публикации информации. 59 | 60 | 61 | ## Дальнейшие шаги 62 | 63 | Теперь, поскольку идея описания у нас есть, Вперед! к [Шагу 1. Описание ресурса](step1-resourse-description.md) 64 | 65 | [🔙](new-endpoint.md) 66 | 67 | [Go next ➡](step1-resourse-description.md) 68 | -------------------------------------------------------------------------------- /documenting-api-endpoints/evaluate-api-referense-docs.md: -------------------------------------------------------------------------------- 1 | # 👨‍💻 Практическое занятие: Оценка ключевых элементов API документации 2 | 3 | После завершения [Обзора пошагового описания API](api-reference-tutorial-overview.md) мы готовы к практике, которая даст нам больше опыта в создании и редактировании документации по API. В этой практике мы и покритикуем и создадим свой собственный раздел API для опен-сорс проекта, [выбранный нами ранее](find-open-source-project.md). 4 | 5 | [Оценка ключевых элементов API документации](#evaluate) 6 | 7 | [Создание или изменение раздела документации API](#create) 8 | 9 | [Следующие шаги](#nextSteps) 10 | 11 | 12 | ## 👨‍💻 Оценка ключевых элементов API документации 13 | 14 | Практическое занятие позволит рассмотреть документацию API и определить общие элементы. Для оценки документации: 15 | 16 | 1. В [списке 100 сайтов с API документацией](../Publishing-doc/API-doc-sites-list.md) или из [ полученного на прошлом практическом занятии результата](../documenting-api-endpoints/find-open-source-project.md) выбираем сайт или несколько сайтов с API документацией 17 | 2. На каждом сайте ищем раздел документации API со списком конечных точек 18 | 3. В документации по каждой ссылке находим информацию: 19 | - [описание ресурса](step1-resourse-description.md); 20 | - [конечные точки и методы](step2-endpoints-and-methods.md): 21 | - [параметры](step3-parameters.md); 22 | - [примеры запроса](step4-request-example.md); 23 | - [примеры ответа и схемы](step5-response-example-and-schema.md); 24 | 25 | > Названия разделов могут отличаться на разных сайтах API-документации, но обычно они легко узнаваемы. 26 | 27 | 4. Оцениваем документацию API, ответив на следующие вопросы для каждого раздела: 28 | - Описание ресурса 29 | - является ли описание action-oriented? 30 | - краткое ли резюме (1-3 предложения)? 31 | - Конечные точки и методы 32 | - как сгруппированы конечные точки (на одной или нескольких страницах? Сгруппированы по методу или по ресурсу)? 33 | - как определены методы для каждой конечной точки? 34 | - Параметры 35 | - сколько параметров у конечной точки (заголовок, путь, строка запроса, параметры тела запроса)? 36 | - определены ли типы данных для каждого параметра (string, boolean, etc)? указаны мин/макс значения? 37 | - Примеры запроса 38 | - в каком формате или на каком языке показан запрос (curl, специфичный язык или другое)? 39 | - сколько параметров включает в себя пример запроса? 40 | - Примеры ответа 41 | - представлены ли ответ и схема ответа? актуально ли описание каждого элемента? 42 | - как сайт документации обрабатывает вложенные иерархии в определениях ответов 43 | 44 | 45 | ## Создание или изменение раздела документации API 46 | 47 | Эта часть задания может быть сложной, но здесь мы начнем создавать примеры для своего портфолио. 48 | 49 | 1. В том же проекте определяем одну из тем API, которую нужно дополнить. (Если у API есть новая конечная точка без документации, можно сфокусироваться на этой конечной точке.) 50 | 2. Заполните раздел, чтобы улучшить его (Если это новая конечная точка, задокументируйте ее) 51 | 3. Создайте [Pull request](../Publishing-doc/Pull-request-workflows.md) и внесите свои изменения в проект 52 | 53 | 54 | ## Следующие шаги 55 | 56 | Теперь, когда мы с головой погрузились в API документацию, пришло время перейти к тестированию. Поскольку мы работаем с конечными точками API и другим кодом, нам нужно будет самостоятельно протестировать эти конечные точки, чтобы собрать и проверить информацию, содержащуюся в документации. Тестирование - не всегда простая штука, поэтому этой теме посвящен целый модуль. Переходим к [обзору тестирования документации](../testing-api-doc/overview-testing.md) 57 | 58 | Но перед тестированием неплохо бы ознакомиться и со [спецификациями OpenAPI и Swagger](../openAPI-specification/README.md) 59 | 60 | [🔙](find-open-source-project.md) 61 | 62 | [Go next ➡](../openAPI-specification/README.md) 63 | -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/1.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/10.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/11.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/12.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/13.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/14.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/15.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/16.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/17.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/18.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/19.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/2.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/20.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/21.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/22.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/22.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/23.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/23.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/24.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/24.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/25.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/25.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/26.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/26.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/27.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/27.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/28.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/28.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/29.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/29.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/3.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/30.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/30.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/31.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/31.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/32.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/33.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/33.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/34.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/34.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/35.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/35.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/36.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/36.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/37.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/37.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/38.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/38.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/4.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/5.png.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/5.png.jpg -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/6.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/7.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/8.png -------------------------------------------------------------------------------- /documenting-api-endpoints/pics/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/documenting-api-endpoints/pics/9.png -------------------------------------------------------------------------------- /documenting-api-endpoints/putt-all-together.md: -------------------------------------------------------------------------------- 1 | # Собираем все вместе 2 | 3 | Давайте соберем различные части вместе, чтобы продемонстрировать полный пример конечной точки: 4 | 5 | ### Surfreport 6 | 7 | Содержит информацию об условиях серфинга, включая высоту прибоя, температуру воды, ветер и прилив. Также предоставляет общую рекомендацию о том, стоит ли заниматься серфингом. 8 | 9 | ### Endpoints 10 | 11 | GET surfreport/{beachId} 12 | 13 | Получает условия серфинга для определенного идентификатора пляжа. 14 | 15 | ## Параметры 16 | 17 | ### Параметры пути 18 | 19 | | Параметр пути | Описание | 20 | |:--|:--| 21 | | {beachId} | Относится к идентификатору пляжа, который вы хотите посмотреть. Все коды beachId доступны на нашем сайте [sampleurl.com](https://sampleurl.com). | 22 | 23 | ### Параметры строки запросах 24 | 25 | | Параметр строки запроса | Обязательно/ необязательно | Описание | Тип данных | 26 | |:--|:--|:--|:--| 27 | | days | Optional | Количество дней, включаемых в ответ. По умолчанию = 3 | Integer | 28 | | time | Optional | При указании времени в ответе будет выводиться только указанный час | Integer. Unix format (ms since 1970) UTC | 29 | 30 | ### Пример запроса 31 | 32 | ```js 33 | curl -I -X GET "https://api.openweathermap.org/data/2.5/surfreport?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial&days=2" 34 | ``` 35 | 36 | ### Пример ответа 37 | 38 | Ниже пример ответа конечной точки `surfreport/{beachId}` 39 | 40 | ```yaml 41 | { 42 | "surfreport": [ 43 | { 44 | "beach": "Santa Cruz", 45 | "monday": { 46 | "1pm": { 47 | "tide": 5, 48 | "wind": 15, 49 | "watertemp": 80, 50 | "surfheight": 5, 51 | "recommendation": "Go surfing!" 52 | }, 53 | "2pm": { 54 | "tide": -1, 55 | "wind": 1, 56 | "watertemp": 50, 57 | "surfheight": 3, 58 | "recommendation": "Surfing conditions are okay, not great." 59 | }, 60 | "3pm": { 61 | "tide": -1, 62 | "wind": 10, 63 | "watertemp": 65, 64 | "surfheight": 1, 65 | "recommendation": "Not a good day for surfing." 66 | } 67 | ... 68 | } 69 | } 70 | ] 71 | } 72 | ``` 73 | 74 | В таблице ниже описание для каждого пункта 75 | 76 | | **Пункт ответа** | **Описание** | **Тип данных** | 77 | |:--|:--|:--| 78 | | **beach** | Пляж, выбранный на основе идентификатора пляжа в запросе. Название пляжа - это официальное название, описанное в базе геоданных Службы национальных парков. | string | 79 | | **{day}** | Выбранный день недели. В ответ возвращается максимум 3 дня. | Object | 80 | | **{time}** | Выбранное время для погодный условий. Этот элемент включается только в том случае, если в запрос включен параметр времени. | string | 81 | | {day}/{time}/**tide** | Уровень прилива на пляже в определенный день и время. Прилив - это расстояние внутри страны, до которого поднимается вода, и может быть положительным или отрицательным числом. При отливе, число отрицательное. При приливе, число положительное. Точка 0 отражает линию, при отсутствии прилива/отлива, и находится в переходе между двумя состояниями. | Integer | 82 | | {day}/{time}/**wind** | Скорость ветра на пляже измеряется в узлах (морских миль в час). Ветер влияет на высоту прибоя и общие условия волнения. Скорость ветра более 15 узлов делает условия серфинга нежелательными, потому что ветер создает белые шапки и неспокойную воду. | Integer | 83 | | {day}/{time}/**watertemp** | Температура воды, возвращаемая в градусах Фаренгейта или Цельсия, в зависимости от указанных единиц измерения. Для температуры воды ниже 70 F может потребоваться гидрокостюм. При температуре ниже 60, вам понадобится как минимум 3-миллиметровый гидрокостюм и желательно пинетки, чтобы согреться. | Integer | 84 | | {day}/{time}/**surfheight** | Высота волн возвращается в футах или сантиметрах в, зависимости от указанных единиц измерения. Высота прибоя 3 фута - минимальный размер, необходимый для серфинга. Если высота прибоя превышает 10 футов, заниматься серфингом небезопасно. | Integer | 85 | | {day}/{time}/**recommendation** | Общая рекомендация, основанная на сочетании различных факторов (ветер, температура воды, высота полета). Возможны три варианта ответа: (1) «Займитесь серфингом!», (2) «Условия серфинга в порядке, но не круто», и (3) «Не очень хороший день для серфинга». Каждый из трех факторов оценивается максимум в 33,33 балла, в зависимости от идеала для каждого элемента. Три элемента объединены, чтобы сформировать процент. От 0% до 59% дает ответ 3, от 60% до 80% дает ответ 2, а от 81% до 100% дает ответ 3. | String | 86 | 87 | Вот и все. При наличии множества конечных точек для документирования, вероятно, проще создать шаблоны, которые следуют общей структуре. Более того, использование спецификации OpenAPI при документировании делает публикацию контента еще проще. Подробнее мы рассмотрим спецификацию OpenAPI в модуле [Спецификация OpenAPI и Swagger](../openAPI-specification/README.md) 88 | 89 | ## Следующие шаги 90 | 91 | Мы закончили [ Обзор пошагового описания API](api-reference-tutorial-overview.md) и теперь готовы к практике: 92 | 93 | - [Поиск open-source проекта](find-open-source-project.md) 94 | - [Оценка ключевых элементов API документации](evaluate-api-referense-docs.md) 95 | 96 | но сначала попробуем поискать [ошибки в документации](whats-wrong.md) 97 | 98 | [🔙](step5-response-example-and-schema.md) 99 | 100 | [Go next ➡](whats-wrong.md) 101 | -------------------------------------------------------------------------------- /documenting-api-endpoints/whats-wrong.md: -------------------------------------------------------------------------------- 1 | # 👨‍💻 Практическое занятие: Что не так в разделе API? 2 | 3 | На этом занятии попробуем раскритиковать справочный раздел API чтоб понять, что там не так. 4 | 5 | [Что не так с разделом API?](#wrong) 6 | 7 | [Surfreport](#surfreport) 8 | 9 | - [Конечные точки](#endpoints) 10 | - [Параметры](#parameters) 11 | - [Пример запроса](#request) 12 | - [Пример ответа](#response) 13 | - [Определения ответа](#definitions) 14 | - [Ответы](#answeres) 15 | 16 | 17 | ## Что не так с разделом API? 18 | 19 | Ниже приведен пример справочной темы по API для конечной точки, которая называется `surfreport`. Там есть примерно 25 ошибок. Копия документации доступна в [Google Docs](https://docs.google.com/document/d/1LU0QJTDHHKFu9FIC24ZrF1I5HC7mzX86fH0YZ1SUHyo/edit) только для чтения. В Google Docs можно перейти в **File> Make a Copy**, чтобы создать свой собственный экземпляр. Затем прокомментировать все ошибки в файле Google Docs. 20 | 21 | ![surfreport](pics/38.png) 22 | 23 | 24 | ## Surfreport 25 | 26 | Понимание того, насколько условия оптимальны для серфинга, является необходимой деталью в жизни каждого серфера. Конечная точка содержит информацию об условиях серфинга, включая высоту прибоя, температуру воды, ветер и прилив. Также предоставляется общая рекомендация о том, стоит ли заниматься серфингом. В качестве бонуса, рекомендации выражены на серферском жаргоне. Лови волну! 27 | 28 | 29 | ### Конечные точки 30 | 31 | **GET/POST** `surfreport/{:beachId}` 32 | 33 | 34 | ### Параметры 35 | 36 | | Параметр | Использование | Описание | Тип данных | 37 | |:--|:--|:--|:--| 38 | | {beachId} | Обязательно | Идентификатор пляжа, о котором нужно получить информацию | Number | 39 | | days | Опционально | Количество дней, отображаемых в ответ. По умолчанию выводит 3, максимальное значение = 10 | Integer | 40 | | time | Опционально | Время, о котором нужно получить отчет | Integer. Формат ISO 8601. Пример: `20180915T155300+0500` | 41 | 42 | 43 | ### Пример запроса 44 | 45 | ``` 46 | https://api.openweathermap.org/data/2.5/surfreport/12345?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&days=1 47 | ``` 48 | 49 | 50 | ### Пример ответа 51 | 52 | ```yaml 53 | { 54 | "surfreport": [ 55 | { 56 | "beach": "Santa Cruz", 57 | "monday": { 58 | "1pm": { 59 | "tide": 5, 60 | "wind": 15, 61 | "watertemp": 80, 62 | "surf_height": 5, 63 | "riptide": "moderate", 64 | "recommendation": "Carve it up, brah! The waves are crankin' wild out there." 65 | }, 66 | "2pm": { 67 | "tide": -1, 68 | "wind": 1, 69 | "watertemp": 50, 70 | "surf_height": 3, 71 | "riptide": "extreme", 72 | "recommendation": "Waves are foam and frothy but rideable in places. Gravitate to the impact zone, due, and hang loose." 73 | }, 74 | "3pm": { 75 | "tide": -1, 76 | "wind": 10, 77 | "watertemp": 65, 78 | "surf_height": 1, 79 | "recommendation": "Scene is blown out. Bail inland and chill on the beach instead or you’ll the one who’ll be shredded, due." 80 | } 81 | ... 82 | } 83 | } 84 | ] 85 | } 86 | ``` 87 | 88 | 89 | ### Определения ответа 90 | 91 | В таблице ниже пояснения по каждому пункту ответа 92 | 93 | | Пункт ответа | Описание | Тип данных | 94 | |:--|:--|:--| 95 | | beach | Выбранный в запросе на основе идентификатора пляж. Название пляжа - это официальное название, описанное в базе геоданных Службы национальных парков | string | 96 | | {day} | Запрошенный (-ые) день (дни) недели | object | 97 | | {time} | Время для которого нужно вывести условия | string | 98 | | tide | Уровень прилива на пляже за определенный день и время. Прилив - это расстояние внутри, до которого поднимается вода, и может быть положительным (прилив) или отрицательным (отлив) числом. При отливе число отрицательное. При приливе число положительное. Точка 0 отражает линию, когда прилив находится в переходе между двумя состояниями | string | 99 | | wind | Скорость ветра на пляже. Ветер влияет на высоту прибоя и общие условия. Скорость ветра более 15 делает условия для серфинга нежелательными, потому что ветер создает белые шапки и неспокойную воду | int | 100 | | waterTemp | Температура воды. При температуре воды ниже 700 F обычно требуется носить гидрокостюм. При температуре ниже 600 F понадобится как минимум 3-миллиметровый гидрокостюм и желательно пинетки, чтобы согреться | string | 101 | | surfheight | Высота волн возвращается в футах или сантиметрах в зависимости от указанных вами единиц измерения. Высота прибоя 3 фута - минимальный размер, необходимый для серфинга. Если высота прибоя превышает 10 футов, заниматься серфингом небезопасно | map | 102 | | recommendation | Общая рекомендация, основанная на сочетании различных факторов (ветра, водной температуры, высоты полета) и т.д. | string | 103 | 104 | 105 | ### Ответы 106 | 107 | Посмотреть ошибки можно в разделе [Описание ошибок](../glossary-and-resourses/answeres-whats-wrong.md) 108 | 109 | [🔙](putt-all-together.md) 110 | 111 | [Go next ➡](find-open-source-project.md) 112 | -------------------------------------------------------------------------------- /glossary-and-resourses/README.md: -------------------------------------------------------------------------------- 1 | # Глоссарий API и источники 2 | 3 | Документация по API полна жаргонов, сокращений и множества новых терминов. 4 | 5 | Этот глоссарий предоставляет список терминов и определений. 6 | 7 | Кроме того, этот раздел содержит дополнительные упражнения и информацию, например, дополнительные действия по вызову API или дополнительную информацию об альтернативных спецификациях. 8 | 9 | # Содержание модуля "Глоссарий API и источники" 10 | 11 | [**Глоссарий API документации**](Glossary-for-API-documentation.md) 12 | 13 | [**Практические занятия REST API**](RESTAPI-activities.md) 14 | 15 | [**Практическое занятие: Получить информацию о событии, используя API сервиса Eventbrite**](Get-event-information-using-Eventbrite-API.md) 16 | 17 | [**Практическое занятие: Извлечь галерею, используя API сервиса Flickr**](Retrieve-gallery-using-Flickr-API.md) 18 | 19 | [**Практическое занятие: Получить скорость ветра, используя API сервиса Aeris Weather**](Get-wind-speed-using-Aeris-API.md) 20 | 21 | [**Справочник RAML**](RAML-tutorial.md) 22 | 23 | [**Справочник API Blueprint**](API-Blueprint-tutorial.md) 24 | 25 | [**Описание ошибок**](answeres-whats-wrong.md) 26 | -------------------------------------------------------------------------------- /glossary-and-resourses/RESTAPI-activities.md: -------------------------------------------------------------------------------- 1 | # Практические занятия REST API 2 | 3 | Чтобы получить больше опыта работы с различными API, рассмотрим несколько примеров в этом модуле "Глоссарий API и источники". Пройдя практику, получим больше информации о различных API-интерфейсах REST, их организации, сложности и взаимозависимости конечных точек и т.д. 4 | 5 | [Доступная практика](#available) 6 | 7 | [Ключи API](#shortcut) 8 | 9 | [Перемены ключа API в примерах кода](#swap) 10 | 11 | 12 | ## Доступная практика 13 | 14 | В этом модуле представлены несколько практических занятий с разными API. Задача указана для каждого занятия. Для начала попытаемся решить проблему самостоятельно. Затем посмотрим приведенные инструкции, чтобы увидеть решение автора курса. 15 | 16 | В таких примерах автор курса просто печатает код на веб-странице, чтобы визуализировать ответ. Доступны следующие практические занятия: 17 | 18 | - [Получить информацию о событии, используя API сервиса Eventbrite](Get-event-information-using-Eventbrite-API.md) 19 | 20 | - [Извлечь галерею, используя API сервиса Flikr](Retrieve-gallery-using-Flickr-API.md) 21 | 22 | - [Получить скорость ветра, используя API сервиса Aeris Weather](Get-wind-speed-using-Aeris-API.md) 23 | 24 | 25 | ## Ключи API 26 | 27 | Каждый API требует использования ключа API, токена или какой-либо другой формы аутентификации. Можно пройти регистрацию и получить свои собственные ключи API, или можно воспользоваться [предоставленными автором ключами](https://idratherbewriting.com/learnapidoc/assets/files/apikeys.txt). 28 | 29 | 30 | 31 | ## Перемены ключа API в примерах кода 32 | 33 | Не стоит вставлять ключи API в примеры кода по следующим причинам: 34 | 35 | - срок действия ключей API истекает; 36 | - ключи API, размещенные в сети, становятся могут использоваться третьими лицами; 37 | - настройка примеров кода - это хорошая вещь. 38 | 39 | Когда мы видим `APIKEY` в примере кода, стоит изменить ключ API. Например, если ключ API был `123`, удаляем `APIKEY` и используем `123`. 40 | -------------------------------------------------------------------------------- /glossary-and-resourses/answeres-whats-wrong.md: -------------------------------------------------------------------------------- 1 | # Описание ошибок 2 | 3 | Здесь разберем ошибки в описании конечной точки Surfreport из [практического занятия: Что не так с разделом API?](../documenting-api-endpoints/whats-wrong.md) 4 | 5 | ### [Описание ресурса](../documenting-api-endpoints/whats-wrong.md#surfreport) 6 | 7 | - много слов, описание должно быть более кратким и ориентированным на действия; 8 | - "Surfreport", в названии не следует использовать заглавные буквы. 9 | 10 | ### [Конечные точки](../documenting-api-endpoints/whats-wrong.md#endpoints) 11 | 12 | - GET/POST: должен быть только один метод, в этом случае GET; 13 | - лишнее двоеточие {:beachId}; 14 | - можно выделить цветом {beachId} 15 | 16 | ### [Параметры](../documenting-api-endpoints/whats-wrong.md#Параметры) 17 | 18 | - параметры строки запроса перемешаны в одной и той же таблице, что и параметры `Path`. Лучше разделить на разные таблицы; 19 | - не понятно, где брать ID пляжа; 20 | - `Number` и `Integer` потенциально противоречивы. Технически `Number` относится к числу с плавающей запятой (float) или к (double) (что допускает десятичные дроби), а `Integer` - это целое число. В данном случае вряд ли идентификаторы пляжа имеют десятичные дроби; 21 | - отсутствует значение параметра `time` по умолчанию; 22 | - что касается типов данных `time`: почему некоторые типы данных имеют примеры, но не все? 23 | 24 | ### [Пример запроса](../documenting-api-endpoints/whats-wrong.md#request) 25 | 26 | - пример запроса не в формате curl; 27 | - показан только один параметр строки запроса, `time` тоже должно быть; 28 | - включен параметр `zip`, но нигде не определен; 29 | - `appID` включает длинный ключ API, который, должен быть сокращен до такой переменной, как `APIKEY`. 30 | 31 | ### [Пример ответа](../documenting-api-endpoints/whats-wrong.md#response) 32 | 33 | - включен `riptide`, но отсутствует его определение в определениях ответа; 34 | - у `riptide` отсутствует запятая во втором экземпляре; 35 | - `riptide` не указан в третьем экземпляре; 36 | - неверное форматирование отступа для `riptide`. 37 | 38 | ### [Определения ответа](../documenting-api-endpoints/whats-wrong.md#definitions) 39 | 40 | - для параметра `wind` не указаны единицы измерения; 41 | - для параметра `wind` "int" следует указывать как "integer"; 42 | - для параметра `watertemp` не указаны единицы измерения; 43 | - тип данных для `surfheight` указан как "Map", а должен быть "integer"; 44 | - `recommendation` не включает в себя более подробную информацию, например, сколько возможных строк с рекомендациями и что они вообще значат; 45 | - `surfheight` должен быть одинаковым: или `surf_height` или `surfheight` и в примере ответа и в таблице определений ответа; 46 | - отсутствует иерархия для дочерних элементов (пример: `tide`, `wind`, `watertemp`) 47 | -------------------------------------------------------------------------------- /glossary-and-resourses/img/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/1.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/10.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/11.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/12.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/13.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/14.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/15.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/16.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/17.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/18.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/19.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/2.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/20.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/21.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/22.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/22.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/3.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/4.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/5.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/6.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/7.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/8.png -------------------------------------------------------------------------------- /glossary-and-resourses/img/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/glossary-and-resourses/img/9.png -------------------------------------------------------------------------------- /introduction-rest-apis/README.md: -------------------------------------------------------------------------------- 1 | 2 | # Введение в REST API 3 | 4 | REST API стали очень популярными в мире IT, и интернет сейчас превращается в совокупность взаимосвязанных API-интерфейсов. 5 | 6 | API REST состоят из запросов и ответов от сервера. 7 | 8 | Технические писатели способные писать документацию для разработчиков имеют огромные перспективы. 9 | 10 | Этот курс поможет разобраться с документацией по API, особенно при помощи практических занятий. 11 | 12 | # Содержание модуля "Введение в REST API" 13 | 14 | [**Обзор курса**](course-overview.md) 15 | 16 | [**Видео презентации**](video-presentations.md) 17 | 18 | [**Слайды курса**](course-slides.md) 19 | 20 | [**Практические занятия**](workshop-activities.md) 21 | 22 | [**Для чего этот курс**](what-for-this-course.md) 23 | 24 | [**Об авторе**](about-the-author.md) 25 | 26 | [**Рынок документации REST API**](api-doc-market.md) 27 | 28 | [**Что такое REST API**](what-is-rest-api.md) 29 | 30 | [**Практика: Определение цели**](identify-goals.md) 31 | 32 | [Go next ➡](course-overview.md) 33 | -------------------------------------------------------------------------------- /introduction-rest-apis/about-the-author.md: -------------------------------------------------------------------------------- 1 | # Об авторе курса 2 | 3 | Немного об авторе курса: Том Джонсон, в настоящее время живет в Калифорнийском Bay Area Сан-Франциско (Саут-Бэй, или Силиконовая долина) и работает в Amazon в Саннивейле. В основном пишет документацию для сторонних разработчиков, создающих приложения для Amazon Appstore, в первую очередь связанных с Fire TV. 4 | 5 | Большинство людей знают его по блогу [I’d Rather Be Writing](https://idratherbewriting.com/), который был активным онлайн-блогом для технических специалистов в течение последнего десятилетия. 6 | 7 | Как и большинство технических писателей, автор столкнулся с этой профессией после работы в других областях. Сначала получил степень бакалавра по английскому языку и степень магистра по литературе, а затем начал свою карьеру в качестве учителя. После работы в области преподавания автор перешел на маркетинговый копирайтинг, а затем стал техническим писателем (в основном по финансовым причинам). 8 | 9 | Несмотря на первоначальное неприятие идеи технического писательства (думал, что это будет скучно), Том Джонсон понял, что ему действительно нравится данная профессия - гораздо больше, чем копирайтинг. Она сочетает в себе мою любовь к письму и увлечение технологией. Получается игра с инструментами и производство всех аспектов контента, от дизайна до стилей и публикации рабочих процессов. 10 | 11 | Несколько лет автор работал обычным техническим писателем, в основном документируя приложения с пользовательскими интерфейсами. Однажды его организация решила уволить команду технических писателей. После этого, и, исходя из склонности к работе с инструментами, он решил направить карьеру на рынок технического письма, который был более востребован: документация для разработчиков, в частности документация API. Он также переехал в Силиконовую долину, чтобы быть в центре технологий. 12 | 13 | Задокументировал свой первый API в стартапе геймификации, а затем перешел на другой полу-стартап, чтобы продолжить с документацией API. После этого перестал работать с приложениями, которые имели пользовательские интерфейсы, и аудитория его документов поменялась: теперь это были в основном разработчиками. Документация для разработчиков была новым полем для исследований с различными инструментами, ожиданиями, целями и результатами. 14 | 15 | Не имея опыта в программировании, автора всегда немного влекло в ту сторону. Будучи учителем, он создал свой собственный интерактивный сайт. В роли технического писателя он часто настраивал или взламывал писательские инструменты и производимые ими артефакты. Было интересно учиться и экспериментировать с новыми технологиями. Документация разработчика очень интересна, и это нравится. 16 | 17 | Тем не менее, автор ни разу не программист. Техническому писателю глубокие технические знания полезны, но не всегда необходимы, так как они, как правило, слишком специализированы и приходят за счет других навыков и знаний. Самое важное - это способность узнавать что-то новое в разных областях и продуктах, даже если это поначалу сложно. А затем сформулировать знания в удобной форме. 18 | 19 | Вы взялись за этот курс, вероятно, потому что хотите развить свои навыки и знания, чтобы расширить свои возможности на работе, повысить конкурентоспособность своего набора навыков или, возможно, выяснить, как задокументировать новый API, который развертывает ваша компания. 20 | 21 | Вы находитесь в правильном месте. К тому времени как вы закончите этот курс, у вас будет четкое понимание того, как документировать API. Вы будете знакомы с правильными инструментами, подходами и методами, необходимыми для успешного создания документации для разработчиков. 22 | 23 | [🔙](what-for-this-course.md) 24 | 25 | [Go next ➡](api-doc-market.md) 26 | -------------------------------------------------------------------------------- /introduction-rest-apis/course-slides.md: -------------------------------------------------------------------------------- 1 | # Слайды курса 2 | 3 | Слайды соответствуют семинарам по API, которые проводил автор курса. Группы слайдов отражают одни и те же модули курса (большинство модулей имеют слайды, но не все). 4 | 5 | [Знакомство с документацией API](https://idratherbewriting.com/learnapidoc/slides/intro_api_documentation.html#/) 6 | 7 | [Используем Api в роли разработчика](https://idratherbewriting.com/learnapidoc/slides/using_api_like_developer.html#/) 8 | 9 | [Документирование конечных точек API](https://idratherbewriting.com/learnapidoc/slides/documenting_api_endpoints.html#/) 10 | 11 | [OpenAPI и Swagger](https://idratherbewriting.com/learnapidoc/slides/openapi_and_swagger.html#/) 12 | 13 | [Безадресный контент в документации API](https://idratherbewriting.com/learnapidoc/slides/nonref_content_api_docs.html#/) 14 | 15 | [Публикация документации API](https://idratherbewriting.com/learnapidoc/slides/publishing_api_docs.html#/) 16 | 17 | [Работа писателя документации API](https://idratherbewriting.com/learnapidoc/slides/getting_job_api_docs.html#/) 18 | 19 | [🔙](video-presentations.md) 20 | 21 | [Go next ➡](workshop-activities.md) 22 | -------------------------------------------------------------------------------- /introduction-rest-apis/identify-goals.md: -------------------------------------------------------------------------------- 1 | # Практическое занятие: Идентификация целей 2 | 3 | Апгрейд документации API, создание портфолио с примерами написания документации API и выполнение всех практик в этом курсе потребуют много времени и усилий. В этом упражнении определяем свои цели и причины для прохождения этого курса. Размышление о мотивации поможет развить правильное мышление и выносливость, чтобы посвятить необходимое время для курса. 4 | 5 | 👨‍💻 **Определение цели документирования API** 6 | 7 | Продумайте цели здесь и убедитесь, что они соответствуют этому курсу. 8 | 9 | Ответьте на следующие вопросы: 10 | 11 | - Для чего вам этот курс? 12 | - Каковы ваши карьерные амбиции, связанные с документацией API? 13 | - Востребована ли работа технического писателя API документации? 14 | - Что вы считаете метрикой успеха для этого курса? 15 | - У вас есть техническое мышление, необходимое для достижения успеха в области документации для разработчиков? 16 | 17 | Для живых семинаров мы обычно делимся ответами в формате, понятном каждому. Но если вы посещаете этот курс онлайн, подумайте о записях своих мыслей в журнале или записи блога. 18 | 19 | [🔙](what-is-rest-api.md) 20 | 21 | [Go next ➡](../like-developer/README.md) 22 | -------------------------------------------------------------------------------- /introduction-rest-apis/pics/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/10.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/11.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/12.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/13.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/14.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/15.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/16.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/17.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/18.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/19.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/2.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/20.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/21.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/22.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/22.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/23.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/23.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/24.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/24.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/25.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/25.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/26.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/26.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/27.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/27.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/28.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/28.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/29.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/29.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/3.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/30.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/30.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/31.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/31.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/32.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/32.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/33.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/33.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/34.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/34.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/35.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/35.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/36.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/36.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/37.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/37.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/38.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/38.jpg -------------------------------------------------------------------------------- /introduction-rest-apis/pics/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/4.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/5.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/6.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/7.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/8.png -------------------------------------------------------------------------------- /introduction-rest-apis/pics/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/introduction-rest-apis/pics/9.png -------------------------------------------------------------------------------- /introduction-rest-apis/video-presentations.md: -------------------------------------------------------------------------------- 1 | # Видео презентации 2 | 3 | Автор провел множество презентаций и семинаров по документации API, и записал большинство из них. Самые последние записи доступны ниже. Помните, что контент API развивается, поэтому некоторые старые презентации могут больше не соответствовать содержанию курса. 4 | 5 | - [Семинар по API в Менло-Парке, Калифорния (8 ноября 2018 г.)](#menlopark) 6 | 7 | - [Видео 1](#video1) 8 | - [Видео 2](#video2) 9 | - [Видео 3](#video3) 10 | - [Видео 4](#video4) 11 | - [Видео 5](#video5) 12 | - [Аудио запись семинара](#audio1) 13 | - [Семинар по API в Денвере, Колорадо (Март 2018)](#denver) 14 | - [Часть I](#part1) 15 | - [Часть II](#part2) 16 | - [Часть III](#part3) 17 | - [Аудио запись семинара](#audio2) 18 | - [Другие записи презентаций API](#other) 19 | - [Вступление в документирование API](#intro) 20 | - [Инструменты и процессы doc-as-code](#doc-as-code) 21 | - [OpenAPI и Swagger](#openapi) 22 | - [Добавление Swagger в API](#swagger) 23 | - [семинар по API в Сакраменто](#sacramento) 24 | 25 | 26 | 27 | ## Семинар по API в Менло-Парке, Калифорния (8 ноября 2018 г.) 28 | 29 | Записи семинара по API документации в Менло-Парке, штат Калифорния, 8 ноября 2018 года. (Более подробную информацию см. [В этом сообщении в блоге](https://idratherbewriting.com/2018/10/31/upcoming-api-doc-workshop/).) Эта запись тесно связана с последним содержанием и упражнениями в этом курсе. Семинар разделен на пять видео. 30 | 31 | 32 | [![Видео 1](pics/31.jpg)](https://youtu.be/X1u453Gtw9g) 33 | 34 | 35 | [![Видео 2](pics/32.jpg)](https://youtu.be/FuZfob2eVb4) 36 | 37 | 38 | [![Видео 3](pics/33.jpg)](https://youtu.be/GgA8772arys) 39 | 40 | 41 | [![Видео 4](pics/34.jpg)](https://youtu.be/mLnea0LLTh4) 42 | 43 | 44 | [![Видео 5](pics/35.jpg)](https://youtu.be/9mSqxqV7TXY) 45 | 46 | Ниже основные моменты всех семинаров собраны в часовое видео: 47 | 48 | [![one-hour](pics/30.jpg)](https://youtu.be/5pzhtrrtkXY) 49 | 50 | Если предпочитаете слушать записи, то ниже ссылки на аудио записи семинаров 51 | 52 | 53 | ### Аудио запись семинара 54 | 55 | [Аудио запись Видео 1](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/menloapidoc/apidocvideo1.mp3) 56 | 57 | [Аудио запись Видео 2](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/menloapidoc/apidocvideo2.mp3) 58 | 59 | [Аудио запись Видео 3](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/menloapidoc/apidocvideo3.mp3) 60 | 61 | [Аудио запись Видео 4](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/menloapidoc/apidocvideo4.mp3) 62 | 63 | [Аудио запись Видео 5](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/menloapidoc/apidocvideo5.mp3) 64 | 65 | 66 | 67 | ## Семинар по API в Денвере, Колорадо (Март 2018) 68 | 69 | Записи семинара по API документации в Денвере, штат Колорадо, 10 марта 2018 года. (Подробнее см. [В этом сообщении в блоге](https://idratherbewriting.com/2018/03/12/api-documentation-workshop-in-denver/)). Эта версия семинара немного отличается от последней версии курса, но содержание хорошее. Видео разделено на три части. 70 | 71 | 72 | [![Часть первая](pics/36.jpg)](https://youtu.be/Ivum3YbOWQ4) 73 | 74 | 75 | [![Часть вторая](pics/37.jpg)](https://youtu.be/zV6m-6_j56w) 76 | 77 | 78 | [![Часть третья](pics/38.jpg)](https://youtu.be/LSLg6Oy1OzM) 79 | 80 | 81 | ### Аудио записи семинара 82 | 83 | Если предпочитаете слушать записи, то ниже ссылки на аудио записи семинаров 84 | 85 | [Аудио записи 1](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/denverapiworkshop_part1.mp3) 86 | 87 | [Аудио записи 2](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/denverapiworkshop_part2.mp3) 88 | 89 | [Аудио записи 3](http://www.podtrac.com/pts/redirect.mp3/idratherassets.com/podcasts/denverapiworkshop_part3.mp3) 90 | 91 | 92 | ## Другие записи презентаций API 93 | 94 | 95 | [Вступление в документирование API](https://youtu.be/NawxzLB4aro) 96 | 97 | 98 | [Инструменты и процессы doc-as-code](https://youtu.be/__vSXJn-JQo) 99 | 100 | [Инструменты и процессы doc-as-code 2](https://youtu.be/Z3e_38WS-2Q) 101 | 102 | 103 | [OpenAPI и Swagger](https://youtu.be/gcDSL-8pkvU) 104 | 105 | 106 | [Добавление Swagger в API](https://youtu.be/wC5hxY0RItQ) 107 | 108 | 109 | [семинар по API в Сакраменто](https://youtu.be/GerbihyUpdo) 110 | 111 | [🔙](course-overview.md) 112 | 113 | [Go next ➡](course-slides.md) 114 | -------------------------------------------------------------------------------- /like-developer/README.md: -------------------------------------------------------------------------------- 1 | # Использование API в роли разработчика 2 | 3 | Роль разработчика поможет лучше понять потребности разработчиков, а также то, что разработчики обычно ищут в документации API. 4 | 5 | Разработчики часто используют такие инструменты, как Postman или curl, для совершения запросов. 6 | 7 | Они смотрят на структуру ответа и динамически интегрируют необходимую информацию в веб-страницы и другие приложения. 8 | 9 | # Содержание модуля "Использование API в роли разработчика" 10 | 11 | [**Сценарий использования API погоды**](using-api-scenario.md) 12 | 13 | [**Получение ключей авторизации**](get-authorization-keys.md) 14 | 15 | [**Отправка запросов в Postman**](submit-requests-postman.md) 16 | 17 | [**Введение и установка curl**](curl-intro-and-instalation.md) 18 | 19 | [**Создание curl запроса**](make-curl-call.md) 20 | 21 | [**Понимание curl**](understand-curl.md) 22 | 23 | [**Использование методов с curl**](use-methods-with-curl.md) 24 | 25 | [**Анализ JSON ответов**](analyze-json-response.md) 26 | 27 | [**Изучение полезных данных JSON ответа**](inspect-json.md) 28 | 29 | [**Доступ и вывод на страницу определенного значения JSON**](access-print-value.md) 30 | 31 | [**Погружение в точечную нотацию**](dot-notation.md) 32 | 33 | 34 | [🔙](../introduction-rest-apis/identify-goals.md) 35 | 36 | [Go next ➡](using-api-scenario.md) 37 | -------------------------------------------------------------------------------- /like-developer/analyze-json-response.md: -------------------------------------------------------------------------------- 1 | # Анализ JSON ответов 2 | 3 | JSON является наиболее распространенным форматом ответов API REST. Посмотрим на ответ JSON для конечной точки прогноза погоды OpenWeatherMap более детально, различая массивы и объекты в JSON. 4 | 5 | [Ответ JSON от конечной точки прогноза погоды OpenWeatherMap](#responce) 6 | 7 | [Объект JSON это пара ключ-значение](#objects) 8 | 9 | [Массив JSON это списки пунктов](#arrays) 10 | 11 | [Состав объектов в массиве и массивов в объекте](#mix) 12 | 13 | [Изучаем ответ прогноза погоды](#examine) 14 | 15 | [Дополнительная информация](#more) 16 | 17 | 18 | ## Ответ JSON от конечной точки прогноза погоды OpenWeatherMap 19 | 20 | JSON расшифровывается как JavaScript Object Notation. Это наиболее распространенный способ возврата информации API REST. Несмотря на то, что некоторые API возвращают информацию как в JSON, так и в XML, лучше использовать JSON для анализа ответа и отображения его на веб-странице. Так как JSON намного лучше вписывается в существующую технологию JavaScript + HTML + CSS, которая поддерживает большинство веб-страниц/ С помощью JavaScript вы можете легко анализировать JSON и интегрировать его в свой веб-контент. 21 | 22 | Развернутый ответ от конечной точки прогноза погоды OpenWeatherMap будет выглядеть примерно так: 23 | 24 | ```yaml 25 | { 26 | "coord": { 27 | "lon": -121.96, 28 | "lat": 37.35 29 | }, 30 | "weather": [ 31 | { 32 | "id": 801, 33 | "main": "Clouds", 34 | "description": "few clouds", 35 | "icon": "02d" 36 | } 37 | ], 38 | "base": "stations", 39 | "main": { 40 | "temp": 70.14, 41 | "pressure": 1012, 42 | "humidity": 33, 43 | "temp_min": 62.6, 44 | "temp_max": 75.2 45 | }, 46 | "visibility": 16093, 47 | "wind": { 48 | "speed": 14.99, 49 | "deg": 330 50 | }, 51 | "clouds": { 52 | "all": 20 53 | }, 54 | "dt": 1522619760, 55 | "sys": { 56 | "type": 1, 57 | "id": 479, 58 | "message": 0.0058, 59 | "country": "US", 60 | "sunrise": 1522590707, 61 | "sunset": 1522636288 62 | }, 63 | "id": 420006397, 64 | "name": "Santa Clara", 65 | "cod": 200 66 | } 67 | ``` 68 | 69 | Проанализируем структуру информации этого ответа ниже. 70 | 71 | 72 | ## Объект JSON это пара ключ-значение 73 | 74 | JSON в совей структуре имеет две базовые сущности: 75 | 76 | - объект; 77 | - массив. 78 | 79 | Объект представляет собой набор пар ключ-значение, заключенных в фигурные скобки: 80 | 81 | ```yaml 82 | { 83 | "key1": "value1", 84 | "key2": "value2" 85 | } 86 | ``` 87 | 88 | Каждая пара ключ-значение заключена в двойные кавычки, и являются строками. Если значение представляет собой integer (целое число) или Boolean (значение true или false), то у значения двойные кавычки не ставятся. Каждая пара ключ-значение отделяется от следующей запятой. 89 | 90 | 91 | ## Массив JSON это списки элементов 92 | 93 | Массивом в JSONe является список элементов, заключенных в квадратные скобки: 94 | 95 | ```yaml 96 | ["first", "second", "third"] 97 | ``` 98 | Список элементов может содержать строки, числа, логические значения, массивы или другие объекты. Для целочисленных или логических значений кавычки не используются. 99 | 100 | Массив целых чисел: 101 | 102 | ```yaml 103 | [1, 2, 3] 104 | ``` 105 | 106 | Массив логических значений: 107 | 108 | ```yaml 109 | [true, false, true] 110 | ``` 111 | 112 | 113 | ## Состав объектов в массиве и массивов в объекте 114 | 115 | JSON может содержать объекты и массивы внутри друг друга. Пример массива объектов: 116 | 117 | ```yaml 118 | [ 119 | object, 120 | object, 121 | object 122 | ] 123 | ``` 124 | 125 | Пример со значениями: 126 | 127 | ```yaml 128 | [ 129 | { 130 | "name":"Tom", 131 | "age":39 132 | }, 133 | { 134 | "name":"Shannon", 135 | "age":37 136 | } 137 | ] 138 | ``` 139 | 140 | Объекты могут содержать массивы в части значения пары ключ-значение: 141 | 142 | ```yaml 143 | { 144 | "children": ["Avery","Callie","lucy","Molly"], 145 | "hobbies": ["swimming","biking","drawing","horseplaying"] 146 | } 147 | ``` 148 | 149 | Нужно помнить, что объекты заключаются в фигурные скобки {} и содержат пары ключ-значение. Иногда эти значения могут являться массивами. Массивы представляют собой списки и заключаются в квадратные скобки []. Обычно массивы содержат списки объектов, а объекты - массивы. 150 | 151 | > Важно понимать разницу между объектами и массивами, потому что это определяет способ доступа и отображения информации. Упражнения с точечной нотацией. которые будут дальше потребуют понимания этой разницы. 152 | 153 | 154 | ## Изучаем ответ прогноза погоды 155 | 156 | Посмотрим на ответ конечной точки погоды API OpenWeatherMap. Что является объектами? Где находятся массивы? Какие объекты являются вложенными? Какие значения являются логическими значениями а какие строками? 157 | 158 | 159 | ## Дополнительная информация 160 | 161 | Для дополнительной информации и понимании формата JSON можно изучить страницу [json.com](http://json.com/) 162 | 163 | [🔙](use-methods-with-curl.md) 164 | 165 | [Go next ➡](inspect-json.md) 166 | -------------------------------------------------------------------------------- /like-developer/curl-intro-and-instalation.md: -------------------------------------------------------------------------------- 1 | # Введение в curl и его установка 2 | 3 | Хотя Postman удобен, его трудно использовать для представления в документации, как совершать запросы с его помощью. Кроме того, разные пользователи, вероятно, используют разные клиенты с графическим интерфейсом или вообще не используют их (предпочитая командную строку) 4 | 5 | Вместо того, чтобы описывать, как выполнять REST-запросы с использованием GUI-клиента, такого как Postman, наиболее традиционный метод документирования синтаксиса запроса - использовать curl. 6 | 7 | [О curl](#about) 8 | 9 | [Установка curl](#instalCurl) 10 | 11 | [Установка на MacOS](#macInstall) 12 | 13 | [Установка на Windows](#winInstall) 14 | 15 | [Создание тестового вызова API](#testCall) 16 | 17 | [curl и Windows](#curlvsWindows) 18 | 19 | 20 | ## О curl 21 | 22 | curl - это утилита командной строки, которая позволяет выполнять HTTP-запросы с различными параметрами и методами. Вместо того, чтобы переходить к веб-ресурсам в адресной строке браузера, можно использовать командную строку, чтобы получить те же ресурсы, извлеченные в виде текста. 23 | 24 | > Иногда curl пишется как cURL, что означает Client URL. "curl" является более распространенным написанием, так что оба варианта верны. 25 | 26 | 27 | ## Установка curl 28 | 29 | curl доступен на MacOS по умолчанию, для Windows требуется установка. Ниже представлены инструкции по установке curl. 30 | 31 | 32 | ### Установка на MacOS 33 | 34 | Проверить установлен ли curl на MacOS можно так: 35 | 36 | 1. Открываем Терминал (нажимаем `Cmd`+`spacebar` для открытия Спотлайт и вводим *Terminal*). 37 | 2. В терминале пишем `curl -V`. Ответ должен быть примерно таким: 38 | 39 | ``` 40 | curl 7.54.0 (x86_64-apple-darwin16.0) libcurl/7.54.0 SecureTransport zlib/1.2.8 41 | Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz UnixSockets 42 | ``` 43 | 44 | Если такого ответа нет, то curl необходимо [скачать и установить](https://curl.haxx.se/) 45 | 46 | 47 | ### Установка на Windows 48 | 49 | Установка curl в Windows включает другие шаги. Сначала определяем версию windows: 32-разрядная или 64-разрядная версия Windows, щелкнув правой кнопкой мыши `Компьютер` и выбрав `Свойства`. Затем следуем [инструкциям на этой странице](http://www.confusedbycode.com/curl/#downloads). Нужно выбрать одну из бесплатных версий с правами Администратора. 50 | 51 | После установки проверяем версию установленной curl; 52 | 53 | 1. Открываем командную строку нажав кнопку `Пуск` и введя `cmd` 54 | 2. В строке пишем `curl -V` 55 | 56 | Ответ должен быть примерно таким: 57 | 58 | ``` 59 | curl 7.54.0 (x86_64-apple-darwin14.0) libcurl/7.37.1 SecureTransport zlib/1.2.5 60 | Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smtp smtps telnet tftp 61 | Features: AsynchDNS GSS-Negotiate IPv6 Largefile NTLM NTLM_WB SSL libz 62 | ``` 63 | 64 | 65 | ## Создание тестового вызова API 66 | 67 | После установки curl делаем тестовый вызов API 68 | 69 | ```javascript 70 | curl -X GET "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial" 71 | ``` 72 | 73 | В ответ должен вернуться мнимизированный JSON: 74 | 75 | ```yaml 76 | {"coord":{"lon":-121.96,"lat":37.35},"weather":[{"id":701,"main":"Mist","description":"mist","icon":"50d"}],"base":"stations","main":{"temp":66.92,"pressure":1017,"humidity":50,"temp_min":53.6,"temp_max":75.2},"visibility":16093,"wind":{"speed":10.29,"deg":300},"clouds":{"all":75},"dt":1522526400,"sys":{"type":1,"id":479,"message":0.0051,"country":"US","sunrise":1522504404,"sunset":1522549829},"id":420006397,"name":"Santa Clara","cod":200} 77 | ``` 78 | 79 | > В Windows в командной строке не работает `Ctrl+V`, нужно нажать правой кнопкой мыши и выбрать `paste`. 80 | 81 | 82 | ## curl и Windows 83 | 84 | Если вы используете Windows, обратите внимание на следующие требования к форматированию при использовании curl: 85 | 86 | - Используйте двойные кавычки в командной строке Windows. (Windows не поддерживает одинарные кавычки.); 87 | - Не используйте обратную косую черту (\) для разделения строк. (Это только для удобства чтения и не влияет на вызов на Mac.) 88 | - Добавив -k в команду curl, вы можете обойти сертификат безопасности curl, который может быть необходимым. 89 | 90 | [🔙](submit-requests-postman.md) 91 | 92 | [Go next ➡](make-curl-call.md) 93 | -------------------------------------------------------------------------------- /like-developer/get-authorization-keys.md: -------------------------------------------------------------------------------- 1 | # Получаем ключ авторизации 2 | 3 | Почти каждый сайт API имеет метод для аутентификации запросов. Обычно мы предоставляем ключ API в своих запросах для получения ответа. Сейчас нам нужно получить ключи API, чтобы отправлять запросы нашему API погоды, а позже изучим [аутентификацию и авторизацию](../conceptual-topics/authentication-and-authorization.md) подробнее. 4 | 5 | [Зачем запросу нужна авторизация](#auth) 6 | 7 | [Практика: Получаем ключ авторизации OpenWeatherMap API](#key) 8 | 9 | [Получаем секретный код и ID Aeris Weather API](#idAeris) 10 | 11 | [Текстовый редактор](#editor) 12 | 13 | 14 | 15 | ## Зачем запросу нужна авторизация 16 | 17 | Требование авторизации позволяет издателям API делать следующее: 18 | 19 | - лицензированный доступ к API; 20 | - оценка лимита количества запросов; 21 | - Контроль доступа определенных функций в API и многое другое. 22 | 23 | Для запуска примеров кода в этом курсе нам нужно будет использовать свои собственные ключи API, поскольку эти ключи обычно обрабатываются как пароли и не выдаются или не публикуются открыто на веб-странице. 24 | 25 | > Если вы хотите позаимствовать ключи API автора курса, вы можете получить их [здесь](https://idratherbewriting.com/learnapidoc/assets/files/apikeys.txt). Иногда бывает, участники семинара зацикливаются на попытках получить ключи API, поэтому автор опубликовал свои ключи здесь, чтобы избежать задержек в работе. 26 | 27 | 28 | ## 👨‍💻 Практика: Получаем ключ авторизации OpenWeatherMap API 29 | 30 | 1. Перейти на страницу [https://openweathermap.org](https://openweathermap.org/) 31 | 2. Нажать `Sign Up` в навигационной панели и создать аккаунт 32 | 3. После создания аккаунта вернуться на страницу [https://openweathermap.org](https://openweathermap.org/) и кликнуть `Sign in` 33 | 4. После входа попадаем в панель разработчика. Кликнуть на плашку `API key` 34 | 5. Сохранить сгенерированный ключ в удобном месте. 35 | 36 | 37 | ## Получаем секретный код и ID Aeris Weather API 38 | 39 | И для контраста, давайте получим ключи для Aeris Weather API. Aeris Weather API требует секретного кода и идентификатора для отправки запросов. 40 | 41 | 1. Открываем сайт [http://www.aerisweather.com](https://www.aerisweather.com/) и нажимаем кнопку `Get started for free` (бесплатная версия ограничивает количество запросов, которые можно сделать). 42 | 3. Вводим username, email и пароль, после чего нажимаем `Sign up for free` для создания аккаунта в сервисе Aeris. После этого входим в аккаунт. 43 | 4. После входа в аккаунт нажимаем `Account` в правом верхнем углу. 44 | 5. Нажимаем `Apps`(во втором навигационном ряду справа от `Usage`) и там выбираем `New Application` 45 | 46 | ![aeris](pics/5.png) 47 | 48 | 6. В диалоговом окне **Add a New Application** вводим следующее: 49 | - **Application Name**: My biking app (or something) 50 | - **Application Namespace**: localhost 51 | 7. Нажимаем `Save App`. 52 | 53 | После регистрации приложения мы должны увидеть его идентификатор, секретный код и пространство имен. Скопируем эту информацию в место, к которому можем легко получить доступ, так как оно понадобится вам для отправки запросов. 54 | 55 | > Помните, то как пользователи авторизуют вызовы с помощью API - это то, что вы обычно описываете в документации API. Далее в курсе мы более подробно рассмотрим [методы авторизации](../conceptual-topics/authentication-and-authorization.md). 56 | 57 | 58 | ## Текстовый редактор 59 | 60 | В предстоящих практических занятиях мы будем работать с кодом в текстовом файле. Для работы с кодом, мы используем текстовый редактор plain text вместо редактора WYSIWYG). Вот несколько вариантов для текстовых редакторов: 61 | 62 | - [Sublime Text (Mac or PC)](http://www.sublimetext.com/) 63 | - [TextWrangler](http://www.barebones.com/products/textwrangler/) or [BBEdit](http://www.barebones.com/products/bbedit/) (Mac) 64 | - [WebStorm (Mac or PC)](https://www.jetbrains.com/webstorm/) 65 | - [Notepad++ (PC)](https://notepad-plus-plus.org/) 66 | - [Atom (Mac or Windows)](https://atom.io/) 67 | - [Komodo Edit (Mac or PC)](https://www.activestate.com/products/komodo-edit/) 68 | - [Coda (Mac)](https://panic.com/coda/) 69 | 70 | Эти редакторы предоставляют функции, которые позволяют вам лучше управлять текстом. Выберите тот, который вы хотите. Избегайте использования TextEdit, так как он добавляет скрытое форматирование, которое может повредить ваш контент. 71 | 72 | 73 | [🔙](using-api-scenario.md) 74 | 75 | [Go next ➡](submit-requests-postman.md) 76 | -------------------------------------------------------------------------------- /like-developer/make-curl-call.md: -------------------------------------------------------------------------------- 1 | # Создаем curl вызов 2 | 3 | В этом разделе будем использовать curl для выполнения тех же запросов API сервиса прогноза, которые делали ранее с помощью Postman. Если curl еще не установлен, то читаем [вводную инструкцию по установке curl](curl-intro-and-instalation.md). 4 | 5 | #### Содержание раздела 6 | 7 | [Создаем запрос к OpenWeatherAPI с помощью curl](#curlRequest) 8 | 9 | [Одинарные и двойные кавычки в запросах curl на Windows](#curlWindows) 10 | 11 | 12 | ## 👨‍💻 Создаем запрос к OpenWeatherAPI с помощью curl 13 | 14 | 1. Предположив, что практическое занятие раздела [Отправка запросов в Postman](submit-requests-postman.md#postmanRequest) выполнено возвращаемся в Postman. 15 | 2. В любом запросе кликаем на кнопку `Code` под кнопкой `Save` 16 | 3. В диалоговом окне "Generate Code Snippets" выбираем cURL из выпадающего списка и нажимаем на кнопку `Copy to Clipboard` 17 | 18 | ![Generate_code_snippets](pics/6.png) 19 | 20 | Код Postman для запроса прогноза погоды OpenWeatherMap выглядит в формате cURL следующим образом: 21 | 22 | ```JavaScript 23 | curl -X GET \ 24 | 'https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147' \ 25 | -H 'Postman-Token: dcf3c17f-ef3f-4711-85e1-c2d928e1ea1a' \ 26 | -H 'cache-control: no-cache' 27 | ``` 28 | 29 | Postman добавил свою информацию о хедере (обозначено -Н) Тэги добавленного заголовка можно удалить. Также можно удалить знаки "\", они добавлены для читаемости текста. 30 | 31 | Кроме того, обратите внимание, что в Windows нужно изменить одинарные кавычки на двойные, потому что одинарные кавычки не поддерживаются в терминале Windows по умолчанию. 32 | 33 | Вот запрос curl с удаленными символами -H и обратной косой чертой, а одинарные кавычки преобразованы в двойные кавычки: 34 | 35 | ```javascript 36 | curl -X GET "https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=fd4698c940c6d1da602a70ac34f0b147" 37 | ``` 38 | 39 | 4. Curl доступен на MacOS по умолчанию. Если на Windows curl еще не установлен, то инструкции по установке по [ссылке](http://www.confusedbycode.com/curl/#downloads), нужно выбрать одну из бесплатных версий с правами Администратора. 40 | 5. Открываем терминал 41 | - на OS Windows нажимаем `ctrl+R` и вводим команду `cmd`, Правой кнопкой мыши вызываем меню и выбираем `Paste` для вставки запроса. 42 | - на MacOS открываем [iTerm](https://www.iterm2.com/) или терминал, нажимая `cmd+Пробел` и вводим команду `Terminal` Вставляем запрос в командную строку и жмем кнопку `Enter`. 43 | 44 | Ответ от OpenWeatherMap на наш запрос будет выглядеть так: 45 | 46 | ```yaml 47 | {"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} 48 | ``` 49 | 50 | Этот запрос минимизирован. Вы можете развернуть его, например на сайте [JSON pretty print](http://jsonprettyprint.com/) или, на MacOS с установленным Python добавив `| python -m json.tool` в конец cURL запроса, чтобы минимизировать JSON в ответе (Для подробностей можно посмотреть ветку на [Stack Overflow](https://stackoverflow.com/questions/352098/how-can-i-pretty-print-json-in-a-shell-script) по этой теме). 51 | 52 | 6. Самостоятельно сделаем curl запрос на 5-дневный прогноз, сохраненный в Postman. И третий API запрос OpenWeatherMap? сохраненный в Postman тоже выполняем в curl 53 | 54 | 55 | ## Одинарные и двойные кавычки в запросах curl на Windows 56 | 57 | При использовании curl на Windows могут возникнуть проблемы с одинарными и двойными кавычками. 58 | 59 | Проблема в том, что содержимое тела запроса часто форматируется в JSON, что требует двойных кавычек. Поскольку вы не можете использовать двойные кавычки внутри других двойных кавычек, вы столкнетесь с проблемами при отправке запросов curl в этих сценариях. 60 | 61 | Вот обходной путь. Если нужно отправить содержимое тела в формате JSON, вы можете сохранить содержимое в файле JSON. Затем вы ссылаетесь на файл символом @, например: 62 | 63 | ```javascript 64 | curl -H "Content-Type: application/json" -H "Authorization: 123" -X POST -d @mypostbody.json http://endpointurl.com/example 65 | ``` 66 | 67 | Здесь curl будет искать в существующем каталоге файл `mypostbody.json`. (Вы также можете указать полный путь к файлу JSON на вашем компьютере.) 68 | 69 | 70 | [🔙](curl-intro-and-instalation.md) 71 | 72 | [Go next ➡](understand-curl.md) 73 | -------------------------------------------------------------------------------- /like-developer/pics/1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/1.jpg -------------------------------------------------------------------------------- /like-developer/pics/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/10.png -------------------------------------------------------------------------------- /like-developer/pics/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/11.png -------------------------------------------------------------------------------- /like-developer/pics/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/12.png -------------------------------------------------------------------------------- /like-developer/pics/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/13.png -------------------------------------------------------------------------------- /like-developer/pics/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/14.png -------------------------------------------------------------------------------- /like-developer/pics/2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/2.jpg -------------------------------------------------------------------------------- /like-developer/pics/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/2.png -------------------------------------------------------------------------------- /like-developer/pics/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/3.png -------------------------------------------------------------------------------- /like-developer/pics/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/4.png -------------------------------------------------------------------------------- /like-developer/pics/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/5.png -------------------------------------------------------------------------------- /like-developer/pics/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/6.png -------------------------------------------------------------------------------- /like-developer/pics/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/7.png -------------------------------------------------------------------------------- /like-developer/pics/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/8.png -------------------------------------------------------------------------------- /like-developer/pics/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/like-developer/pics/9.png -------------------------------------------------------------------------------- /openAPI-specification/README.md: -------------------------------------------------------------------------------- 1 | # Спецификация OpenAPI и Swagger 2 | 3 | Спецификация OpenAPI предоставляет один из способов описания REST API и включает все разделы, упомянутые в предыдущем разделе [**Документирование конечных точек API.**](../documenting-api-endpoints/README.md) Фреймворки, такие как Swagger UI, могут анализировать спецификацию OpenAPI и генерировать интерактивную документацию, которая позволяет пользователям опробовать точки доступа при изучении API. 4 | 5 | # Содержание модуля "Спецификация OpenAPI и Swagger" 6 | 7 | [**Обзор форматов спецификаций REST API**](overview-specification-formats.md) 8 | 9 | [**Знакомство со спецификациями OpenAPI и Swagger**](introduction-openapi-and-swagger.md) 10 | 11 | [**Работа в YAML**](working-in-YAML.md) 12 | 13 | [**Обзор руководства OpenAPI**](openapi-tutorial-overview.md) 14 | 15 | [**Шаг 1: Объект `openapi`**](step1-openapi-object.md) 16 | 17 | [**Шаг 2: Объект `info`**](step2-info-object.md) 18 | 19 | [**Шаг3: Объект `servers`**](step3-servers-object.md) 20 | 21 | [**Шаг 4: Объект `paths`**](step4-paths-object.md) 22 | 23 | [**Шаг 5: Объект `components`**](step5-components-object.md) 24 | 25 | [**Шаг 6: Объект `security`**](step6-security-object.md) 26 | 27 | [**Шаг 7: Объект `tags`**](step7-tags-object.md) 28 | 29 | [**Шаг 8: Объект `externalDocs`**](step8-externalDocs-object.md) 30 | 31 | [**Практическое занятие: Создание спецификации OpenAPI**](create-openapi-specification.md) 32 | 33 | [**Руководство Swagger UI**](swagger-ui-tutorial.md) 34 | 35 | [**Демо Swagger UI**](swagger-ui-demo.md) 36 | 37 | [**Введение и руководство SwaggerHub**](swaggerhub-introduction-and-tutorial.md) 38 | 39 | [**Stoplight - инструмент визуального моделирования для создания спецификаций**](stoplight.md) 40 | 41 | [**Интеграция Swagger с документацией**](integrating-swagger-with-docs.md) 42 | 43 | 44 | [🔙](../documenting-api-endpoints/evaluate-api-referense-docs.md) 45 | 46 | [Go next ➡](overview-specification-formats.md) 47 | -------------------------------------------------------------------------------- /openAPI-specification/create-openapi-specification.md: -------------------------------------------------------------------------------- 1 | # Практическое занятие: Создание спецификации OpenAPI 2 | 3 | В [руководстве по OpenAPI](openapi-tutorial-overview.md) мы прошли 8 этапов создания документа в спецификации OpenAPI. Теперь стоит попрактиковаться сначала в редактировании, а затем и в создании документа спецификации OpenAPI. 4 | 5 | #### Содержание раздела 6 | 7 | [Практическое занятие: редакция существующего документа в спецификации OpenAPI](#edit) 8 | 9 | [Создание документа в спецификации OpenAPI для выбранного API](#create) 10 | 11 | 12 | ## 👨‍💻 Практическое занятие: редакция существующего документа в спецификации OpenAPI 13 | 14 | Используем простой [API Sunrise and sunset times](https://sunrise-sunset.org/api), чтобы лучше ознакомиться с процессом редактирования файла спецификации OpenAPI. [API Sunrise and sunset times](https://sunrise-sunset.org/api) не требует аутентификации с запросами, поэтому здесь отсутствуют сложные рабочие процессы аутентификации (можно пропустить [объект `security`](step6-security-object.md)). В этом упражнении мы отредактируем некоторые из существующих значений в уже написанном документе спецификации OpenAPI. 15 | 16 | Для редактирования спецификации OpenAPI: 17 | 18 | 1. Копируем код из [предварительно созданной спецификации OpenAPI](https://idratherbewriting.com/learnapidoc/assets/files/swagger-sunrise-sunset/openapi_sunrise_sunset.yml) 19 | 20 | 2. Вставляем содержимое YAML в [редактор Swagger](https://editor.swagger.io/). 21 | 22 | 3. Определяем каждый из объектов корневого уровня спецификации OpenAPI: 23 | 24 | - [Шаг 1: Объект `openapi`](step1-openapi-object.md) 25 | - [Шаг 2: Объект `info`](step2-info-object.md) 26 | - [Шаг 3: Объект `servers`](step3-servers-object.md) 27 | - [Шаг 4: объект `paths`](step4-paths-object.md) 28 | - [Шаг 5: Объект `components`](step5-components-object.md) 29 | - [Шаг 6: Объект `security`](step6-security-object.md) 30 | - [Шаг 7: Объект `tags`](step7-tags-object.md) 31 | - [Шаг 8: Объект `externalDocs`](step8-externalDocs-object.md) 32 | 33 | 4. В объекте `info`(в верхней части) внесите изменения в свойство `description` и посмотрите, как обновляется визуальный дисплей в правом столбце. 34 | 5. В объекте `parameters` внесите изменения в одно из свойств описания и посмотрите, как обновляется визуальный редактор. 35 | 6. Найдите указатель `$ref` в объекте `response`. Определите, на что он указывает в `components`. 36 | 7. Измените несколько интервалов таким образом, чтобы сделать спецификацию недействительной (например, вставить пробел перед информацией), и посмотрите на появившуюся ошибку. Затем верните неверный пробел. 37 | 8. Разверните раздел **Get** и нажмите `Try it out`. Затем нажмите `Execute` и посмотрите ответ. 38 | 39 | 40 | 41 | 42 | ## 👨‍💻 Создание документа в спецификации OpenAPI для выбранного API 43 | 44 | [На практике 3 модуля мы искали опен-сорс проект API](../documenting-api-endpoints/find-open-source-project.md), которому нужна была документация. Сейчас попробуем создать спецификацию OpenAPI для этого API. В зависимости от API, с которым мы решили работать, можно будет использовать этот документ как часть своего портфолио. 45 | 46 | Если этот опен-сорс проект не имеет API или API уже имеет спецификацию OpenAPI, можно найти другой API (возможно, из этого [списка из 100+ API](../Publishing-doc/API-doc-sites-list.md)) и создать спецификацию OpenAPI. 47 | 48 | При создании спецификации пройдем по каждому шагу руководства по спецификации OpenAPI, чтобы создать документацию API: 49 | 50 | - [Шаг 1: Объект `openapi`](step1-openapi-object.md) 51 | - [Шаг 2: Объект `info`](step2-info-object.md) 52 | - [Шаг 3: Объект `servers`](step3-servers-object.md) 53 | - [Шаг 4: объект `paths`](step4-paths-object.md) 54 | - [Шаг 5: Объект `components`](step5-components-object.md) 55 | - [Шаг 6: Объект `security`](step6-security-object.md) 56 | - [Шаг 7: Объект `tags`](step7-tags-object.md) 57 | - [Шаг 8: Объект `externalDocs`](step8-externalDocs-object.md) 58 | 59 | После создания проверяем нашу документацию в [редакторе Swagger](https://swagger.io/tools/swagger-editor/). Выполним запрос, чтобы убедиться, что все работает верно. 60 | 61 | 62 | [🔙](step8-externalDocs-object.md) 63 | 64 | [Go next ➡](swagger-ui-tutorial.md) 65 | -------------------------------------------------------------------------------- /openAPI-specification/img/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/1.png -------------------------------------------------------------------------------- /openAPI-specification/img/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/10.png -------------------------------------------------------------------------------- /openAPI-specification/img/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/11.png -------------------------------------------------------------------------------- /openAPI-specification/img/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/12.png -------------------------------------------------------------------------------- /openAPI-specification/img/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/13.png -------------------------------------------------------------------------------- /openAPI-specification/img/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/14.png -------------------------------------------------------------------------------- /openAPI-specification/img/15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/15.png -------------------------------------------------------------------------------- /openAPI-specification/img/16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/16.png -------------------------------------------------------------------------------- /openAPI-specification/img/17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/17.png -------------------------------------------------------------------------------- /openAPI-specification/img/18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/18.png -------------------------------------------------------------------------------- /openAPI-specification/img/19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/19.png -------------------------------------------------------------------------------- /openAPI-specification/img/2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/2.jpg -------------------------------------------------------------------------------- /openAPI-specification/img/20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/20.png -------------------------------------------------------------------------------- /openAPI-specification/img/21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/21.png -------------------------------------------------------------------------------- /openAPI-specification/img/22.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/22.png -------------------------------------------------------------------------------- /openAPI-specification/img/23.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/23.png -------------------------------------------------------------------------------- /openAPI-specification/img/24.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/24.png -------------------------------------------------------------------------------- /openAPI-specification/img/25.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/25.png -------------------------------------------------------------------------------- /openAPI-specification/img/26.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/26.png -------------------------------------------------------------------------------- /openAPI-specification/img/27.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/27.png -------------------------------------------------------------------------------- /openAPI-specification/img/28.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/28.png -------------------------------------------------------------------------------- /openAPI-specification/img/29.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/29.png -------------------------------------------------------------------------------- /openAPI-specification/img/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/3.png -------------------------------------------------------------------------------- /openAPI-specification/img/30.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/30.png -------------------------------------------------------------------------------- /openAPI-specification/img/31.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/31.png -------------------------------------------------------------------------------- /openAPI-specification/img/32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/32.png -------------------------------------------------------------------------------- /openAPI-specification/img/33.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/33.png -------------------------------------------------------------------------------- /openAPI-specification/img/34.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/34.png -------------------------------------------------------------------------------- /openAPI-specification/img/35.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/35.png -------------------------------------------------------------------------------- /openAPI-specification/img/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/4.png -------------------------------------------------------------------------------- /openAPI-specification/img/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/5.png -------------------------------------------------------------------------------- /openAPI-specification/img/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/6.png -------------------------------------------------------------------------------- /openAPI-specification/img/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/7.png -------------------------------------------------------------------------------- /openAPI-specification/img/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/8.png -------------------------------------------------------------------------------- /openAPI-specification/img/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/9.png -------------------------------------------------------------------------------- /openAPI-specification/img/youtube.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/openAPI-specification/img/youtube.jpg -------------------------------------------------------------------------------- /openAPI-specification/overview-specification-formats.md: -------------------------------------------------------------------------------- 1 | # Обзор форматов спецификаций REST API 2 | 3 | При [знакомстве с REST API](../introduction-rest-apis/what-is-rest-api.md), было упомянуто, что REST API следуют архитектурному стилю, а не конкретному стандарту. Тем не менее, было разработано несколько спецификаций REST, чтобы попытаться представить стандарты в виде описания API REST. Вот три наиболее популярных спецификации REST API: [OpenAPI (формально называется Swagger)](https://github.com/OAI/OpenAPI-Specification), [RAML](https://raml.org/) и [API Blueprint](https://apiblueprint.org/). 4 | 5 | В первые годы спецификаций между форматами существовала здоровая конкуренция. Но теперь, без сомнения, спецификация OpenAPI является самой популярной, с наибольшим сообществом, динамикой и различными инструментами. Из-за этого больше всего времени уделено OpenAPI в этом курсе. Фактически весь этот модуль посвящен спецификации OpenAPI. ([RAML](../glossary-and-resourses/RAML-tutorial.md) и [API Blueprint](../glossary-and-resourses/API-Blueprint-tutorial.md) размещены в модуле [Глоссарий API и источники](../glossary-and-resourses/README.md) в конце курса.) 6 | 7 | > «OpenAPI» относится к спецификации, а «Swagger» относится к инструментам API, которые считывают и отображают информацию в спецификации. Подробный рассказ об OpenAPI и Swagger в следующих разделах. 8 | 9 | В целом, спецификации REST API приводят к улучшению структуры документации. Помните, что эти спецификации REST API в основном описывают эталонные [конечные точки в API](../documenting-api-endpoints/README.md). Хотя эти разделы важны, помимо них необходима еще и иная документации. (Вот почему создан отдельный модуль [концептуальные разделы API](../conceptual-topics/README.md).) 10 | 11 | Тем не менее, документация, которую покрывает спецификация, часто составляет основную ценность API, поскольку она касается конечных точек и их ответов. 12 | 13 | Запись в спецификации вводит новое измерение в документацию, которое делает документацию API по существу уникальной. Овладев форматом спецификации OpenAPI, мы сможем значительно отличаться от других технических писателей. 14 | 15 | 16 | [🔙](README.md) 17 | 18 | [Go next ➡](introduction-openapi-and-swagger.md) 19 | -------------------------------------------------------------------------------- /openAPI-specification/step2-info-object.md: -------------------------------------------------------------------------------- 1 | # Руководство OpenAPI Шаг 2: Объект `info` 2 | 3 | | [*Шаг 1: объект* `openapi`](step1-openapi-object.md) | --> | [**Шаг 2: объект** `info`](step2-info-object.md) | --> | [*Шаг 3: объект* `servers`](step3-servers-object.md) | --> | [*Шаг 4: объект* `paths`](step4-paths-object.md) | --> | [*Шаг 5: объект* `components`](step5-components-object.md) | --> | [*Шаг 6: объект* `security`](step6-security-object.md) | --> | [*Шаг 7: объект* `tags`](step7-tags-object.md) | --> | [*Шаг 8: объект* `externalDocs`](step8-externalDocs-object.md) | 4 | 5 | Объект `info` содержит основную информацию о вашем API, включая заголовок, описание, версию, ссылку на лицензию, ссылку на условия обслуживания и контактную информацию. Многие из свойств являются необязательными. 6 | 7 | [Пример объекта `info`](#sample) 8 | 9 | [Отображение в Swagger UI](#appearance) 10 | 11 | 12 | ## Пример объекта `info` 13 | 14 | Вот пример объекта `info` и его свойств 15 | 16 | ```yaml 17 | openapi: "3.0.2" 18 | info: 19 | title: "OpenWeatherMap API" 20 | description: "Get the current weather, daily forecast for 16 days, and a three-hour-interval forecast for 5 days for your city. Helpful stats, graphics, and this day in history charts are available for your reference. Interactive maps show precipitation, clouds, pressure, wind around your location stations. Data is available in JSON, XML, or HTML format. **Note**: This sample Swagger file covers the `current` endpoint only from the OpenWeatherMap API.

**Note**: All parameters are optional, but you must select at least one parameter. Calling the API by city ID (using the `id` parameter) will provide the most precise location results." 21 | version: "2.5" 22 | termsOfService: "https://openweathermap.org/terms" 23 | contact: 24 | name: "OpenWeatherMap API" 25 | url: "https://openweathermap.org/api" 26 | email: "some_email@gmail.com" 27 | license: 28 | name: "CC Attribution-ShareAlike 4.0 (CC BY-SA 4.0)" 29 | url: "https://openweathermap.org/price" 30 | ``` 31 | 32 | > При описании свойств можно использовать [CommonMark Markdown](https://spec.commonmark.org/0.27/), который более точен, однозначен и надежен, чем оригинальный Markdown. Например, CommonMark Markdown предлагает [обратные слэши](https://spec.commonmark.org/0.27/#backslash-escapes) и точно определяет, сколько пробелов нужно в списках и других пунктуациях. Также можно переходить на новые строки с помощью `\n` и избегать проблемные символы, такие как кавычки или двоеточия с обратной косой чертой. 33 | 34 | При написании контента в свойствах `description`, нужно обратить внимание, что двоеточия являются проблематичными в YAML, потому что они обозначают новые уровни. Либо избегайте двоеточий с обратной косой чертой, либо заключите значение `description` в кавычки. Можно использовать одинарные или двойные кавычки для значений свойств. (Если заключать значения в кавычки, в текстовых редакторах может отображаться подсветка кода свойств и значений.) 35 | 36 | 37 | ## Отображение в Swagger UI 38 | 39 | Двигаемся дальше: вставляем [код](#sample) вместе с объектом `openapi` из предыдущего шага в редактор Swagger. В Swagger UI отображены ошибки рендеринга (поскольку в документе спецификации еще нет объектов `path`), но содержимое все равно будет отображаться. (Можно пока свернуть окно ошибок в верхней части нажав `Hide`). 40 | 41 | Информация в Swagger UI будет отображаться следующим образом: 42 | 43 | ![info](img/6.png) 44 | 45 | В `description`, в дополнение к описанию общего API, можно предоставить пользователям несколько основных инструкций по использованию Swagger UI. Если есть тестовая учетная запись, которую они должны использовать, можно предоставить им необходимую информацию в этом поле. 46 | 47 | [🔙](step1-openapi-object.md) 48 | 49 | [Go next ➡](step3-servers-object.md) 50 | -------------------------------------------------------------------------------- /openAPI-specification/step3-servers-object.md: -------------------------------------------------------------------------------- 1 | # Руководство OpenAPI Шаг 3: Объект `servers` 2 | 3 | | [*Шаг 1: объект* `openapi`](step1-openapi-object.md) | --> | [*Шаг 2: объект* `info`](step2-info-object.md) | --> | [**Шаг 3: объект** `servers`](step3-servers-object.md) | --> | [*Шаг 4: объект* `paths`](step4-paths-object.md) | --> | [*Шаг 5: объект* `components`](step5-components-object.md) | --> | [*Шаг 6: объект* `security`](step6-security-object.md) | --> | [*Шаг 7: объект* `tags`](step7-tags-object.md) | --> | [*Шаг 8: объект* `externalDocs`](step8-externalDocs-object.md) | 4 | 5 | В объекте `servers` указывается базовый путь, используемый в ваших запросах API. Базовый путь - это часть URL, которая находится перед конечной точкой. 6 | 7 | [Пример объекта `servers`](#sample) 8 | 9 | [Опции URL сервера](#options) 10 | 11 | [Отображение в Swagger UI](#appearance) 12 | 13 | 14 | ## Пример объекта `servers` 15 | 16 | Пример объекта `servers` 17 | 18 | ``` 19 | servers: 20 | - url: https://api.openweathermap.org/data/2.5/ 21 | ``` 22 | 23 | Каждая из конечных точек (называемых в спецификации `paths`) будет добавляться ​​к URL-адресу сервера, при отправке пользователями пробных запросов `Try it out`. Например, если одним из путей является` /weather`, то при отправке запроса Swagger UI представит путь к `{server URL}{path}` или [https://api.openweathermap.org/data/2.5/weather](https://api.openweathermap.org/data/2.5/weather). 24 | 25 | ## Опции URL сервера 26 | 27 | Объект `servers` обладает гибкой настройкой. Можно указать несколько URL-адресов серверов, которые могут относиться к различным средам (тестовая, бета-версия, рабочая версия). При наличии нескольких URL-адресов серверов, пользователи могут выбирать среду в раскрывающемся списке серверов. Можно указать несколько URL-адресов серверов, например: 28 | 29 | ``` 30 | servers: 31 | - url: https://api.openweathermap.org/data/2.5/ 32 | description: Production server 33 | - url: http://beta.api.openweathermap.org/data/2.5/ 34 | description: Beta server 35 | - url: http://some-other.api.openweathermap.org/data/2.5/ 36 | description: Some other server 37 | ``` 38 | 39 | В Swagger UI выбор из нескольких серверов осуществляется при помощи выпадающего списка 40 | 41 | ![multiservers](img/7.png) 42 | 43 | Если указан один сервер все равно будет отображаться выпадающий список, но с одним вариантом. 44 | 45 | В URL-адрес сервера также можно включать переменные, которые будут заполняться сервером во время выполнения. Кроме того, если для разных путей (конечных точек) требуются разные URL-адреса сервера, можно добавить объект `servers` в качестве свойства в объекте операции объекта `path`. URL-адрес локально объявленных серверов переопределяет URL-адрес глобальных серверов. 46 | 47 | См. [Overriding Servers](https://swagger.io/docs/specification/api-host-and-base-path/) в разделе «Сервер API и базовый URL» (документы Swagger) для получения дополнительной информации. 48 | 49 | 50 | ## 👨‍💻 Отображение в Swagger UI 51 | 52 | Вставим объект `servers` (первый пример кода выше, показывающий только один URL) в редактор Swagger, добавив к имеющемуся коду. Swagger UI будет выглядеть следующим образом: 53 | 54 | ![servers](img/8.png) 55 | 56 | 57 | [🔙](step2-info-object.md) 58 | 59 | [Go next ➡](step4-paths-object.md) 60 | -------------------------------------------------------------------------------- /openAPI-specification/step7-tags-object.md: -------------------------------------------------------------------------------- 1 | # Руководство OpenAPI Шаг 7: Объект `tags` 2 | 3 | | [*Шаг 1: объект* `openapi`](step1-openapi-object.md) | --> | [*Шаг 2: объект* `info`](step2-info-object.md) | --> | [*Шаг 3: объект* `servers`](step3-servers-object.md) | --> | [*Шаг 4: объект* `paths`](step4-paths-object.md) | --> | [*Шаг 5: объект* `components`](step5-components-object.md) | --> | [*Шаг 6: объект* `security`](step6-security-object.md) | --> | [**Шаг 7: объект** `tags`](step7-tags-object.md) | --> | [*Шаг 8: объект* `externalDocs`](step8-externalDocs-object.md) | 4 | 5 | Объект `tags` позволяет группировать пути (конечные точки) в Swagger UI. 6 | 7 | [Определение `tags` на корневом уровне](#define) 8 | 9 | [`tags` на уровне объекта `paths`](#level) 10 | 11 | [Отображение в Swagger UI](#appearanse) 12 | 13 | 14 | ## Определение `tags` на корневом уровне 15 | 16 | На корневом уровне [объект `tags`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#tagObject) перечисляет все теги, которые используются в [объектах `operations`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject) (которые появляются в объекте `paths`, как описано в [Шаге 4: объект `paths`](step4-paths-object.md) ). Вот пример объекта тегов для нашего API OpenWeatherMap: 17 | 18 | ```yaml 19 | tags: 20 | - name: Current Weather Data 21 | description: "Get current weather details" 22 | ``` 23 | 24 | Здесь только один тег, но их может быть столько, сколько вы хотите (если у вас много конечных точек, имеет смысл создать несколько тегов для их группировки). Вы можете перечислить как `name`, так и `description` для каждого тега. `description` отображается в виде подзаголовка для имени тега на дисплее пользовательского интерфейса Swagger. 25 | 26 | 27 | ## Тэги на уровне объекта `paths` 28 | 29 | Объект `tags` на корневом уровне должен содержать список всех тегов (групп), которые вы хотите использовать в своем API. Затем в каждом объекте пути под `paths` вы указываете тег, под которым вы хотите сгруппировать этот путь. 30 | 31 | Например, в объекте операций для `/current` пути мы использовали тег `Current Weather Data`: 32 | 33 | ```yaml 34 | paths: 35 | /weather: 36 | get: 37 | tags: 38 | - Current Weather Data 39 | ``` 40 | 41 | Этот тег определен на глобальном уровне, поэтому путь `/weather` будет сгруппирован здесь. 42 | 43 | 44 | ## Отображение в Swagger UI 45 | 46 | Добавьте следующий код к корневому уровню документа OpenAPI в редакторе Swagger: 47 | 48 | ```yaml 49 | tags: 50 | - name: Current Weather Data 51 | description: "Get current weather details" 52 | ``` 53 | 54 | Посмотрите, как описание отображается рядом со свернутым разделом «Данные о текущей погоде». 55 | 56 | ![tags](img/16.png) 57 | 58 | > Тэг определен на корневом уровне 59 | 60 | 61 | Все пути, имеющие одинаковый тег, сгруппированы на дисплее. Например, пути с тегом `Current Weather Data` будут сгруппированы под заголовком `Current Weather Data`. Каждое название группы представляет собой кнопку, которая сворачивает / разворачивает вложенную информацию. 62 | 63 | ![name](img/17.png) 64 | 65 | Порядок тегов в объекте `tags` на корневом уровне определяет их порядок в интерфейсе Swagger. Кроме того, `descriptions` появляются справа от имени тега. 66 | 67 | В нашем примере спецификации OpenAPI теги не кажутся необходимыми, поскольку мы просто документируем один путь / конечную точку. (Кроме того, настроена [демо версию Swagger UI](swagger-ui-demo.md) для расширения раздела по умолчанию.) Но представьте, что у вас есть надежный API с более чем 30 путями описания. Вы наверняка захотите организовать пути в логические группы для навигации пользователей. 68 | 69 | [🔙](step6-security-object.md) 70 | 71 | [Go next ➡](step8-externalDocs-object.md) 72 | -------------------------------------------------------------------------------- /openAPI-specification/step8-externalDocs-object.md: -------------------------------------------------------------------------------- 1 | # Руководство OpenAPI Шаг 8: Объект `externalDocs` 2 | 3 | | [*Шаг 1: объект* `openapi`](step1-openapi-object.md) | --> | [*Шаг 2: объект* `info`](step2-info-object.md) | --> | [*Шаг 3: объект* `servers`](step3-servers-object.md) | --> | [*Шаг 4: объект* `paths`](step4-paths-object.md) | --> | [*Шаг 5: объект* `components`](step5-components-object.md) | --> | [*Шаг 6: объект* `security`](step6-security-object.md) | --> | [*Шаг 7: объект* `tags`](step7-tags-object.md) | --> | [**Шаг 8: объект** `externalDocs`](step8-externalDocs-object.md) | 4 | 5 | [Объект `externalDocs`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#external-documentation-object) позволяет добавлять ссылки на внешнюю документацию. Можно добавлять ссылки на внешние документы в объекте `paths`. 6 | 7 | [Пример объекта `externalDocs`](#example) 8 | 9 | [Отображение в Swagger UI](#appearanse) 10 | 11 | [Итоговый результат](#finish) 12 | 13 | 14 | ## Пример объекта `externalDocs` 15 | 16 | Вот пример объекта `externalDocs`: 17 | 18 | ```yaml 19 | externalDocs: 20 | description: API Documentation 21 | url: https://openweathermap.org/api 22 | ``` 23 | 24 | Обратите внимание, что эта документация должна относиться в целом к API. Чтобы связать определенный параметр с дополнительной документацией, можно добавить объект `externalDocs` к объекту операции, как отмечено в описании [Объекта `operations`](step4-paths-object.md#%operations) в Шаге 4: Объект `paths`. 25 | 26 | 27 | ## Отображение в Swagger UI 28 | 29 | Добавим приведенный выше код к корневому уровню документа OpenAPI в интерфейсе Swagger. 30 | 31 | В Swagger UI после описания API появится ссылка вместе с информацией об API: 32 | 33 | ![externaldoc](img/18.png) 34 | 35 | > Ссылка на внешнюю документацию 36 | 37 | На данный момент, мы можем догадаться о некоторых проблемам интеграции Swagger UI с остальной частью нашей документации. Скорее всего, будет два вывода и полуфрагментированный пользовательский опыт. Объект `externalDocs` обеспечивает предсказуемое место для ссылки [концептуальных разделов](../conceptual-topics/README.md). См. [Интеграция Swagger UI со сторонними документами](integrating-swagger-with-docs.md) для получения дополнительной информации о стратегиях интеграции. 38 | 39 | 40 | ## Итоговый результат 41 | 42 | Теперь, когда мы выполнили все шаги в руководстве OpenAPI, мы закончили создание нашего документа спецификации OpenAPI. Итоговый вариант спецификации здесь: [https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml](https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml) 43 | 44 | Вот как выглядит собранная в Swagger UI спецификация: 45 | 46 | ![final](img/19.png) 47 | 48 | 49 | [🔙](step7-tags-object.md) 50 | 51 | [Go next ➡](create-openapi-specification.md) 52 | -------------------------------------------------------------------------------- /openAPI-specification/swagger-ui-demo.md: -------------------------------------------------------------------------------- 1 | # Демо Swagger UI 2 | 3 | При использовании Swagger UI, вывод Swagger UI не обязательно должен быть [автономным сайтом](https://idratherbewriting.com/learnapidoc/assets/files/swagger/). Можно встроить Swagger в существующую веб-страницу. Ниже приведен встроенный экземпляр [Swagger UI](https://github.com/swagger-api/swagger-ui), показывающий файл [OpenAPI для OpenWeatherMapAPI](https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml). 4 | 5 | Дисплей пользовательского интерфейса Swagger спроектирован так, чтобы быть отзывчивым, однако сворачиваемые разделы в модели по-прежнему имеют недостатки переполнения в представлениях, поэтому при встраивании можно столкнуться с некоторыми проблемами. 6 | 7 | 8 | [🔙](swagger-ui-tutorial.md) 9 | 10 | [Go next ➡](swaggerhub-introduction-and-tutorial.md) 11 | -------------------------------------------------------------------------------- /testing-api-doc/README.md: -------------------------------------------------------------------------------- 1 | # Тестирование документации 2 | 3 | Тестирование документации имеет решающее значение для предоставления точной, полной информации. 4 | 5 | Из-за высокого уровня сложности и технических требований документации API и иной документации разработчиков многие технические писатели склонны брать информацию из такой документации и добавлять ее без личного тестирования. 6 | 7 | Однако простая игра в редакционную/издательскую функцию может сделать из вас простого секретаря. 8 | 9 | # Содержание модуля "Тестирование документации" 10 | 11 | [**Обзор тестирования документации**](overview-testing.md) 12 | 13 | [**Настройка тестовой среды окружения**](set-up-test-environment.md) 14 | 15 | [**Самостоятельное тестирование всех инструкций**](test-instructions-yourself.md) 16 | 17 | [**Тестирование предположений**](test-assumptions.md) 18 | 19 | [**Практическое занятие: Тестирование документации проекта**](test-documentation.md) 20 | 21 | [🔙](../openAPI-specification/integrating-swagger-with-docs.md) 22 | 23 | [Go next ➡](overview-testing.md) 24 | -------------------------------------------------------------------------------- /testing-api-doc/img/1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/testing-api-doc/img/1.jpg -------------------------------------------------------------------------------- /testing-api-doc/img/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/testing-api-doc/img/2.png -------------------------------------------------------------------------------- /testing-api-doc/img/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/testing-api-doc/img/3.png -------------------------------------------------------------------------------- /testing-api-doc/img/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docops-hq/learnapidoc-ru/f6927496ed1213eff57bfce78f172ebb4a5cddf5/testing-api-doc/img/4.png -------------------------------------------------------------------------------- /testing-api-doc/overview-testing.md: -------------------------------------------------------------------------------- 1 | # Обзор тестирования документации 2 | 3 | До сих пор мы были сильно сосредоточены на документации API. В этом разделе рассмотрим аспект документации API, который, возможно, более применим ко всем типам документации, но который особенно важен для документации для разработчиков, где тестирование и экспериментирование с продуктами и услугами не всегда просты. 4 | 5 | Самостоятельно пройти весь цикл жизни документации важно для создания качественных и точных инструкций. Чем сложнее настройка, тем сложнее протестировать все шаги. Тем не менее, если мы хотим выйти за рамки простого редактирования и публикации документации, написанной инженером, нам необходимо создать примеры приложений или настроить системы, необходимые для тестирования документации по API. Эти тесты должны схожими как можно ближе с тем, что фактические пользователи будут делать. 6 | 7 | #### Содержание раздела 8 | 9 | [Использование тестовых случаев из QA](#leverage) 10 | 11 | [Способы тестирования контента](#testWays) 12 | 13 | 14 | ## Использование тестовых случаев из QA 15 | 16 | Когда начинаем настраивать тесты для своей документации, обычно мы взаимодействуем с группой обеспечения качества (QA, отдел тестирования). Разработчики могут быть также полезны, но команда обеспечения качества уже имеет, предположительно, систему тестирования, обычно тестовый сервер, и тестовые случаи. «Тестовые случаи» - это различные сценарии, по которым продукт должен быть проверен. 17 | 18 | С командой тестирования стоит дружить и узнавать лучшие практики для тестирования сценариев, соответствующих документации. Как правило, эти люди могут помочь эффективно приступить к работе, и они будут рады видеть нового члена команды. Если тех.писатель обнаружит ошибки, он может переслать их в QA или зарегистрировать их самостоятельно в баг треккере группы. 19 | 20 | Если мы можем подключиться к набору тестов, которые команды QA используют для выполнения тестов, можно начать с задокументированных заданий. В хороших тестовых примерах обычно перечисляются шаги, необходимые для получения результата, и сценарии могут наводить на нужную документацию. 21 | 22 | 23 | ## Способы тестирования контента 24 | 25 | Тестирование API-документации настолько критично, что автором курса выделен целый модуль, посвященный этой теме. Этот раздел включает три темы: 26 | 27 | - [Настройка тестовой среды окружения](set-up-test-environment.md) 28 | - [Самостоятельное тестирование всех инструкций](test-instructions-yourself.md) 29 | - [Тестирование предположений](test-assumptions.md) 30 | 31 | ![tester](img/1.jpg) 32 | > Фото взято из фотобанка [Flikr](https://www.flickr.com/photos/seattlemunicipalarchives/3739366791/) [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/legalcode) - Городская лаборатория по испытанию воды, 1948 год. Тестировщик документации, как ученый в лаборатории, тщательно настраивающем тесты для измерения реакций и результатов. 33 | 34 | [🔙](README.md) 35 | 36 | [Go next ➡](set-up-test-environment.md) 37 | -------------------------------------------------------------------------------- /testing-api-doc/test-documentation.md: -------------------------------------------------------------------------------- 1 | # 👨‍💻 Практическое занятие: Тестирование документации проекта 2 | 3 | Теперь, когда почитали о тестировании, пришло время немного попрактиковаться. В этом упражнении мы проведем тестирование документации опен-сорс проекта (или другим проектом, который вы для себя определили). 4 | 5 | #### Содержание раздела 6 | 7 | [Тестирование раздела](#topicTest) 8 | 9 | [Изучение деталей](#details) 10 | 11 | 12 | ## Тестирование раздела 13 | 14 | 1. В [выбранном проекте](../documenting-api-endpoints/find-open-source-project.md#docNeed) ищем следующие разделы: 15 | 16 | - Getting started tutorial (или похожий); 17 | - API endpoint. 18 | 19 | 2. Тестируем документацию проходя по всем деталям. Особенно: 20 | 21 | - для `Getting started tutorial` выполняем все шаги. Записываем любые предположения, которые показались запутанными, новые или незнакомые термины или сокращения и другие появившиеся вопросы. Сколько времени понадобилось, чтобы завершить учебное пособие по началу работы? 22 | - для конечной точки API создаем запрос и изучаем ответ. Соответствует ли ответ тому, что находится в документации? Пробуем разные варианты параметров в конечной точке и смотрим, соответствуют ли ответы ожидаемым. Определяем любую неправильную, отсутствующую или неточную информацию. 23 | 24 | 3. Если нашлась неверная информацию, либо зарегистрируйте проблему, либо обратитесь к руководителю отдела обеспечения качества с обратной связью. 25 | 26 | 27 | ## Изучение деталей 28 | 29 | Определяем, кто выполняет тестирование по проекту. Можно связаться с руководителем отдела обеспечения качества проекта и собрать как можно больше информации о том, как проводится тестирование. Ищем ответы на следующие вопросы: 30 | 31 | - существуют ли тестовые случаи для выполнения различных сценариев в проекте? 32 | - где хранятся тестовые случаи? 33 | - как выполняются тесты: автоматически или вручную? 34 | - какой вид тестирования проводит команда перед релизом? 35 | - если вы столкнулись с ошибкой во время тестирования, как вы должны сообщить об этом? 36 | 37 | [🔙](test-assumptions.md) 38 | 39 | [Go next ➡](../conceptual-topics/README.md) 40 | --------------------------------------------------------------------------------