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

Документация по API - один из самых недооцененных активов технологической компании. Большинство технологических компаний продают доступ к API, которые позволяют клиентам получать информацию или пользоваться услугами. Затем доход генерируется каждый раз, когда клиент использует API. Чтобы клиенты могли использовать API, они должны понимать, что доступно, как их запрашивать и как они будут возвращены. Вся эта информация должна быть представлена ​​в документации API, обычно в виде веб-сайта. Поэтому очень важно, чтобы ваша документация по API была работоспособной, доступной, переносимой и интегрированной.

В Stoplight мы хотим помочь компаниям создать красивую и удобную документацию по API. Мы видим ценность, которую он может принести как компаниям, так и их клиентам. Вот почему мы решили создать инструмент для облегчения этого процесса. В Stoplight Classic, первом поколении нашей платформы API, мы создали инструмент, который автоматически генерирует документацию для вашего API и публикует ее как одностраничное веб-приложение. Это означает, что вместо получения нового файла HTML каждый раз, когда пользователь перемещается, страницы создаются динамически в браузере с использованием JavaScript. Это позволяет нам обслуживать десятки тысяч веб-сайтов без необходимости хранить какие-либо файлы HTML. Теоретически это звучит здорово, но со временем мы пришли к выводу, что у этого метода есть некоторые недостатки.

Проблемы с нашей документацией по API

Быстрая онлайн-документация

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

SEO дружественный и доступный

Это ужасно для SEO. Почти все поисковые роботы, такие как Google, индексируют первый HTML-файл, который возвращается при переходе по URL-адресу. Для одностраничных приложений это обычно означает загрузочный счетчик, поскольку содержимое страницы не будет отображаться до тех пор, пока не будет загружен файл JavaScript.

Портативный

Поскольку статические файлы не создаются, было непросто перенести опубликованную документацию на существующий веб-сайт или портал для разработчиков. Большинство наших клиентов прибегали к встраиванию своей документации через HTML iFrame. Теоретически это работает, но не поддерживает ссылки на подстраницы.

Интегрированный

Документация по API не всегда является автономной. В большинстве случаев компании хотят включать свою документацию по API вместе с документацией по продукту. Обычно это называется порталом для разработчиков, а в Stoplight - Hub. Возможно разделение на два, но это не идеально для пользователей, которым приходится перемещаться между несколькими сайтами.

Наши решения для размещенной документации

Чтобы решить первую проблему длительного времени загрузки, мы решили удалить ненужное подключение к нашей базе данных. Всякий раз, когда кто-то хотел просмотреть опубликованный веб-сайт API Docs, браузеру необходимо было загрузить как файл JavaScript, так и некоторые данные из нашей базы данных Mongo, расположенной на востоке США. Это добавило нашим клиентам в Азии средней задержки ~ 220 мс. Чтобы уменьшить эту задержку, мы решили хранить все документы, используемые для рендеринга веб-сайта API Docs, в AWS S3. Затем мы воспользовались преимуществами CloudFront CDN для обслуживания этих документов из точек по всему миру, значительно сократив задержку.

Каждый веб-сайт API Docs будет хранить один файл, который в основном представлял собой спецификацию OpenAPI с некоторыми дополнительными метаданными, такими как маршруты страниц, темы и параметры конфигурации в S3. Этот файл JSON был загружен одновременно с файлом JavaScript, и вместе они использовались для визуализации содержимого документации. Этот процесс сработал именно так, как мы ожидали, и снизил задержку для наших клиентов в других частях мира, но не решил наши оставшиеся проблемы. С этой целью мы начали переосмысливать то, как мы создавали веб-сайты с документацией.

Мы решили создать нашу собственную спецификацию, которая могла бы объединить любое количество документов спецификации OpenAPI, файлов Markdown и HTML с использованием ссылок JSON. С его помощью инструмент сборки, который может экспортировать спецификацию на портал разработчика, оптимизированный для SEO и переносимости. Так родились спецификация Hub и Hub Builder:

Hub Builder дал нам комбинацию статического веб-сайта (отлично подходит для SEO) и одностраничного приложения (отлично подходит для производительности). Первоначальный запрос веб-страницы загружает предварительно обработанный HTML-файл, содержащий все содержимое и метатеги, а также код JavaScript, необходимый для визуализации всех последующих страниц. Файлы HTML имеют небольшой размер и загружаются значительно быстрее, чем файлы JavaScript большего размера. Это означает, что начальная загрузка страницы происходит практически мгновенно, сканеры могут очищать статические файлы HTML на предмет метатегов, а наши клиенты могут загружать свои веб-сайты с полной документацией и размещать их там, где они захотят.

Посмотрите на эти улучшения производительности, сравнивая наше первое решение (Классическое) с тем, что у нас есть сейчас с Hub Builder (Далее): среднее время загрузки страницы сократилось примерно на 75%.

Следующие шаги

В Stoplight мы всегда ищем инновационные решения для поддержания баланса между эстетикой и функциональностью. Мы не хотим, чтобы вам пришлось жертвовать красивой документацией ради скорости и производительности. Мы также не хотим, чтобы процесс создания документации был трудоемким и трудоемким. Изменения, которые мы внесли до сих пор, были нашей первой попыткой установить этот баланс, но это только начало. У нас уже есть планы по дальнейшему ускорению процесса, а также множество новых функций и услуг. Думаю, вам просто нужно подождать и посмотреть!

Мы начали рассылку новостей на Stoplight с некоторых сообщений в блогах за месяц, наших любимых сообщений из сообщества API и многого другого! Зарегистрируйтесь ниже 👇