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

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

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

Если вы давно знакомы с Backend Development, то, конечно же, знакомы и со Swagger. Swagger — это набор правил, спецификаций и инструментов с открытым исходным кодом для разработки и описания RESTful API. Фреймворк Swagger позволяет разработчикам создавать интерактивную, удобочитаемую для машин и человека документацию по API. С помощью этих инструментов вы можете легко создавать документацию для членов команды. Swagger также широко используется, потому что он использует спецификацию OpenAPI — отраслевой стандарт для разработки RESTful API.

Те из вас, кто часто использует ExpressJS для создания службы API, могут использовать этот Swagger для документирования создаваемого вами API. В этом уроке я помогу вам внедрить swagger в ваш проект Express. в конце руководства вы также можете загрузить исходный код, который я обсуждал в этом руководстве.

И так, чего же ты ждешь? давайте начнем делать документацию по API!

Предпосылка

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

Здесь я создам несколько CRUD API, которые будут использоваться в этом руководстве:

Мы видим, что здесь я создал 5 конечных точек с помощью ExpressJS. все эти конечные точки будут иметь собственную документацию, чтобы разработчикам было проще внедрять их в пользовательский интерфейс.

Установка swagger-ui-express

Чтобы добавить чванства в наш проект, мы можем добавить библиотеку, используя npm.

npm install swagger-ui-express

Интеграция Swagger в Express

После того, как библиотека установлена, пришло время интегрировать ее в Express! откройте основной файл. затем введите часть этого кода:

В приведенном выше коде мы делаем несколько вещей. Давайте обсудим их один за другим:

  • Импортируем библиотеку swagger-ui-express в index.js
  • Мы готовим swagger.json в качестве основного источника нашей документации по API.
  • Подготавливаем варианты библиотеки.
  • Мы определяем конечную точку («/api-docs»), которая обрабатывает документацию по API и выполняет все необходимые здесь функции.

Наша задача по созданию документации API на данном этапе не выполнена, когда мы попытаемся запустить наш проект, появится ошибка, как показано ниже:

Из этой ошибки мы можем сказать, что Swagger не может найти файл swagger.json, который будет основным источником нашей документации по API. Это потому, что файл еще не существует.

Тогда как решить эту ошибку? конечно, создав файл. есть 2 способа сделать это: создать спецификационный файл вручную или сгенерировать спецификационный файл в соответствии с API, который мы создали ранее.

Первый способ, который вы можете сделать, — это если вы действительно понимаете, как писать Open API. как я объяснял ранее, Swagger использует стандарт Open API при написании своей документации. последней версией Open API на данный момент является версия 3.0. Если вам интересно научиться писать Open API, вы можете прочитать документацию здесь:
https://swagger.io/docs/specification/about/

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

Попробуем второй способ, конечно, было бы очень неплохо, не правда ли, если бы можно было сэкономить время на составление документации?

Создать файл спецификации

Первый шаг, который мы должны сделать, это добавить библиотеку в наш проект. мы можем использовать npm, чтобы добавить его.

npm install --save-dev swagger-autogen

После того, как библиотека установлена, добавляем в наш проект 1 файл. Этот файл позже поможет нам в создании файла спецификаций.

В приведенном выше коде мы делаем несколько вещей:

  • Сначала мы добавляем в файл библиотеку swagger-autogen, затем инициализируем ее с помощью последней конфигурации Open API (3.0.0).
  • Затем мы определили сгенерированный файл в выходном файле.
  • После этого мы определили файлы маршрутизатора, которые мы используем в проекте. В данном случае я использовал app.js в качестве основного маршрутизатора.
  • Мы также определили объект конфигурации для создания файла спецификаций. Я объясню позже относительно этого объекта конфигурации.
  • Наконец, мы генерируем файл спецификаций с помощью функции swaggerAutogen().

Запустите этот файл, используя узел ‹filename›, после чего мы получим уведомление о том, что библиотека успешно сгенерировала спецификационный файл. мы также можем увидеть файл спецификации, который мы уже создали.

Теперь попробуем снова запустить наш проект. и вуаля! ошибка исчезла.

Чтение документации

После того, как наш проект будет запущен, мы перейдем к созданной ранее конечной точке (/api-docs). и мы видим, что документация Swagger UI API здесь работает.

С помощью этого пользовательского интерфейса Swagger мы можем видеть, какие конечные точки мы создали, какие параметры необходимы, какие методы поддерживаются, и даже мы можем напрямую попробовать API без помощи других инструментов, таких как Postman или Rest API Client. очень практично не так ли?

Пользовательская информация в конечной точке

Если мы посмотрим на это с первого взгляда, информация по умолчанию, сгенерированная swagger-autogen, на самом деле довольно полная. мы можем видеть, какие параметры нужны, какие методы поддерживаются, какой код ответа будет выдан и так далее. однако что произойдет, если вам нужно предоставить дополнительную информацию другим разработчикам? например, какой идентификатор должен быть передан в вышеуказанный API, или каково использование вышеуказанного API?

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

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

Давайте добавим несколько строк кода в наш маршрутизатор:

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

Снова создайте файл спецификаций, затем снова запустите наш проект. теперь информация в пользовательском интерфейсе Swagger изменится, как показано ниже:

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

Авторизация API

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

Одним из методов, обычно используемых для защиты API, является использование токенов JWT. Этот токен позже будет отправлен через заголовок, чтобы проверить, действителен он или нет. Вопрос в том, поддерживает ли Swagger безопасность API с помощью токена JWT?

Ответ: конечно Да! вы можете легко добавить проверку, чтобы API мог нормально работать. чтобы добавить процесс авторизации в Swagger Express, вы можете запустить его, добавив код, как показано ниже:

В этом коде мы добавляем новую конфигурацию в виде определений безопасности. мы устанавливаем носитель безопасности в формате JWT в этом объекте определений безопасности. он работает для добавления глобального заголовка безопасности в пользовательский интерфейс Swagger. после этого мы также добавляем роль безопасности на наш маршрут.

Как видите, в коде мы добавляем #swagger-security для обработки роли безопасности на маршруте.

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

Мы также можем видеть значок замка на нашей защищенной конечной точке, которую мы настроили ранее. это означает, что для использования этой конечной точки мы должны сначала ввести действительный токен JWT.

Заключение

Подводя итог, можно легко создать API документации в Express с помощью библиотек swagger-ui-express и swagger-autogen. с этими двумя библиотеками вам не нужно вручную создавать документацию. Эту документацию по API также можно использовать для проверки ответа напрямую без помощи других клиентов Rest, таких как Postman.

Если вы заинтересованы в загрузке исходного кода в этом руководстве, посетите мою учетную запись Github.

https://github.com/arrif-arrijal/express-swagger-doc

Подключиться дальше

  • Не забудьте подписаться на Medium, Twitter или Email.
  • Если вы думаете о подписке на Medium, вы можете помочь мне, используя мою реферальную ссылку.
  • Свяжитесь со мной в LinkedIn, если вы хотите обсудить, вам нужна помощь или поговорить о бизнес-запросах.