На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- OpenMRS
- Технический писатель:
- Саураб
- Название проекта:
- Расширение удобной для пользователя документации GitHub для REST API
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Основная цель
Дополните документацию по REST API на основе OpenMRS Swagger, добавив рекомендации по использованию API.
Описание Проекта
API REST OpenMRS — это один из ключевых механизмов доступа разработчиков к данным из OpenMRS. Уже существует автоматически созданная документация на основе Swagger для API веб-сервисов OpenMRS, а также статическая документация на основе GitHub. Мы должны расширить эту документацию на основе GitHub в этом сезоне документации.
КРАТКИЙ ОБЗОР
После небольшого исследования OpenMRS Talk, как предложил Берк, я узнал, что этот проект начался еще в 2017 году как проект GSOC. С Гаяном Виракутти, основной целью которого было улучшение существующей документации OpenMRS REST API путем улучшения спецификации Swagger и улучшения способа создания спецификации Swagger, чтобы была создана улучшенная версия самой документации Swagger. Все соответствующие детали, реализованные в проекте, были обобщены здесь, в этом ток-посте OpenMRS, и оказались весьма полезными.
Затем, в 2019 году, этот проект был переработан, и мы отказались от изменений в документации Swagger, создав его вариации. Вместо этого мы разработали статическую документацию, удобную для GitHub, которую собираемся расширить в этом сезоне документации.
Итак, краткое описание текущего проектного предложения, которое я собираюсь описать, таково:
- Придумываем примеры на некоторых популярных языках (в частности, на Java и JavaScript).
- Добавление поддержки игровой площадки для документации планшета, аналогично функции «опробования» Swagger.
- Рефакторинг и улучшение проделанной до сих пор работы.
- Поиск и добавление недостающих ресурсов.
- Добавление немного дополнительного описания в раздел консоли документации.
ПОДРОБНОЕ ОПИСАНИЕ
- Придумайте примеры на разных языках.
Я бы предложил добавить примеры на Java, которые будут основаны на SDK, а затем добавить примеры модернизации, которые, я думаю, добавят больше глубины нашей документации, поскольку добавление примеров на еще одном языке, таком как JavaScript, не будет такой большой помощью, как добавление примеров модернизации, поскольку я Я использовал эти REST API во время работы над Android-клиентом OpenMRS, и у меня не было ресурсов, к которым можно было бы обратиться, когда мне требовалась помощь с использованием конечных точек специально для Android. И я мог бы серьезно привести здесь несколько качественных примеров, учитывая мой опыт работы с конечными точками API OpenMRS в клиенте Android. Я обсужу это со своими наставниками и поработаю над тем, что будет решено. Кроме того, помимо добавления примеров поддерживаемых операций, нам также следует добавить примеры аутентификации на серверах OpenMRS на некоторых языках программирования. На данный момент у нас есть только примеры использования Curl.
- Добавление поддержки Playground для тестирования примеров API
Я использовал эту функцию в документации OpenMRS, размещенной на демонстрационном сервере, и это действительно удобный инструмент, который можно использовать в любой документации API. Я немного поисследовал здесь, и оказалось, что встроить спецификацию Swagger-UI в текущую статическую документацию не так уж и сложно. Используя переключатели отображения и текущий код документации Swagger, который у нас есть. Таким образом, мы можем даже гарантировать, что пробная функция останется актуальной в соответствии с текущими спецификациями API. Я считаю, что это один из способов интегрировать функции игровой площадки в нашу текущую статическую документацию.
- Рефакторинг и улучшение проделанной до сих пор работы.
Проверка текущих примеров завивки
Этот раздел является одним из основных направлений этого проекта в этом году. В настоящее время в документации GitHub API есть только примеры Curl, некоторые из которых нельзя напрямую запустить на демонстрационном сервере для проверки непосредственно из браузера. Я протестирую все текущие конечные точки и буду поддерживать простой документ с различными примерами ответов на завитки, которые мы получаем при выполнении этих запросов на завивку. Я буду использовать Postman в дополнение к встроенной пробной функции в документации Swagger, чтобы выполнить эту задачу, если потребуется.
Отсутствуют ответы API в некоторых примерах.
Некоторые ответы были добавлены к настоящим примерам Curl, но некоторые примеры Curl не содержат ответов. Я думаю, даже если ответы не являются подробными, что обычно бывает при таких операциях, как очистка ресурса, у нас должен быть пример ответа JSON API, хотя мы задокументировали все возможные коды ответов и причину их получения. Я думаю, это сделало бы примеры в документации API более единообразны !!
Отсутствуют рабочие примеры по различным операциям
Я думаю, что это будет самая важная часть рефакторинга ранее проделанной работы в документации API. В документации есть конкретные примеры, которые можно напрямую выполнить с помощью cURL, но некоторые из них немного абстрактны, что дает хорошую ссылку на опытные примеры. разработчиков, но оставляет новичков в замешательстве. Как я понял из этого поста в разговоре об OpenMRS, хорошие примеры бесценны, поэтому, помимо добавления примеров работы, мы могли бы поддерживать подсветку синтаксиса, что на самом деле не так уж и сложно, оно в значительной степени поставляется в комплекте с slate, что делает это довольно простым, как я узнал здесь,
Как Берк много раз подчеркивал в своем посте, предпочитая простоту и наглядность в документации вместо хорошего пользовательского интерфейса и блестящего интерфейса, я бы придерживался этих принципов и попытался сделать ранее задокументированные конечные точки как можно более наглядными, поговорив с разработчиками, которые в настоящее время работают над OpenMRS Webservices API и привлечение сообщества, точно так же, как я сделал в ток-посте для сбора описаний типов атрибутов для ресурсов форм, которые были мне непонятны в моем пиаре здесь. Я бы действительно поработал над приоритетами, поговорил со своими наставниками и решил, какие вещи действительно повышают ценность документации и которые необходимо выполнить в первую очередь.
Добавление вариантов использования в качестве явного заголовка
Я просмотрел множество документации по API, просто чтобы разобраться в них, и увидел, что во всех из них варианты использования указаны в явном заголовке, хотя у нас есть варианты использования, они не видны явно, они несколько объединены в определениях и примерах, которые следуют. после определений ресурсов и подресурсов, я думаю, нам следует попытаться отделить варианты использования как отдельный объект в документации, чтобы разработчикам на самом деле не приходилось искать определения, выявляющие варианты использования, а просто посмотрите их.
Поиск и документирование недостающих ресурсов
Ресурсы текущего состояния проекта перечислены здесь, но, увидев здесь последнюю версию документации Swagger, я смог определить множество ресурсов, которые можно было бы добавить к текущему набору ресурсов в документации API, дружественной к GitHub, с описанием, как и в других ресурсы во время сезона документации 2019. Я буду обсуждать темы, которые необходимо добавить в документацию, и добавлять их соответствующим образом.
ЗАКЛЮЧЕНИЕ
Я уже некоторое время являюсь частью сообщества OpenMRS. Я активно участвую в проекте Android Client, где часто взаимодействую с API для взаимодействия с серверами. Следовательно, я чувствую, что могу работать над этим проектом по расширению документации API довольно хорошо, поскольку я могу сам рассматривать свою работу как разработчика и оценивать, действительно ли это облегчает работу других разработчиков или нет. Я познакомился с инструментами, используемыми для удобный для пользователя репозиторий документации, размещенный здесь, я также внес несколько изменений в этот репозиторий, чтобы ознакомиться с репозиторием и инструментами, например, slateUI. Поскольку считается, что API так же хорош, как и его документация, поэтому я хотел бы сделать API-интерфейсы OpenMRS Rest немного улучшены за счет улучшения документации.
Я буду еженедельно сообщать о прогрессе в обсуждениях, которые помогут получить обратную связь от сообщества и работать в тесном сотрудничестве с моим наставником и сообществом, чтобы извлечь максимальную пользу из этого периода документации.