Сваггер vs Обертки

Всем привет!

В этой статье поговорим о Swagger (Свагере) и Wrappers (Обертки).

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

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

Например, можно посмотреть на вот такие обертки для Jira: jiraclient (обертка для работы с REST API Jira через JavaScript), питоновский клиент Jira .

Зачем нам нужны обертки?

Я буду рассказывать про обертки и сваггер в контексте продуктов Atlassian, но все эти же идет могут быть применены и для других продуктов.

Обертки позволяют нам работать с REST API легче. Например, давайте воспользуемся нашей JS оберткой, чтобы получить данные для запроса:

// With ES6
import JiraApi from 'jira-client';

// Initialize
var jira = new JiraApi({
  protocol: 'https',
  host: 'jira.somehost.com',
  username: 'username',
  password: 'password',
  apiVersion: '2',
  strictSSL: true
});

async function logIssueName() {
  try {
    const issue = await jira.findIssue(issueNumber);
    console.log(`Status: ${issue.fields.status.name}`);
  } catch (err) {
    console.error(err);
  }
}

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

Тоже самое для питоновской библиотеки:

jira = Jira(
    url='http://localhost:8080',
    username='admin',
    password='admin')
JQL = 'project = DEMO AND status IN ("To Do", "In Progress") ORDER BY issuekey'
data = jira.jql(JQL)
print(data)

Опять инициализировали подлкючение и вызвали метод jql. Очень простой и понятный код.

Я думаю, теперь понятно для чего нужны обертки.

Тогда зачем Сваггер?

Обертки широко использовались до появления Сваггера.

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

Я сделаю детальный пример в этой статье.

Я доработаю плагин jira-react-atlaskit, который я сделал для того, чтобы показать, как использовать React и Atlaskit в серверных плагинах.

Я добавлю туда код, который будет выбирать все проекты из Jira Cloud с помощью swagger-js.

В реальном приложении я не делал бы это через фронтенд, а использовал бы бэкенд, который написан на Java. В этом случае я бы использовал библиотеку swagger-codegen. Это бы сделало наше приложение более безопасным.

Но в рамках этой статьи я все буду делать на фронтенде.

Меняем бэкенд

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

Вам нужно скачать этот файл и поменять параметр servers:

"servers":[{"url":"https://your-domain.atlassian.com"}]

Замените url на url Вашего Jira Cloud.

Далее нам нужно сделать этот файл доступным в моем Jira Server плагине. Поэтому я его положил в папку backend/src/main/resources/swagger. Имя файл swagger.v3.json.

Далее я добавил ссылку на него в дескрипторе web-resource в файле atlassian-plugin.xml:

<resource type="download" name="swagger/" location="/swagger"/>

Теперь мне нужно передать путь к файлу в мой JS код.

Для этого я добавлю параметер с этим путем для передачи в мой шаблон soy в файле backend/src/main/java/ru/matveev/alexey/atlas/jira/servlet/FormServlet.java

 map.put("pathtoswaggerjson", "/jira/download/resources/ru.matveev.alexey.atlas.jira.backend:jira-react-atlaskit-resources/swagger/swagger.v3.json");

И прочитаю этот параметр в моем файле soy.

        <input class="text" type="text" id="pathtoswaggerjson" name="pathtoswaggerjson" value="{$pathtoswaggerjson}">

Отлично! Бэкенд готов.

Меняем фронтенд

Сначала добавим зависимость на библиотеку swagger-js в файл frontend/package.json:

"swagger-client": "^3.11.0",

Теперь будем менять код в файле frontend/src/js/components/Form.js.

Сначала импортируем сваггер клиента:

import SwaggerClient from 'swagger-client';

А теперь поменяем наш конструктор.

Получаем путь на файл swagger.v3.json:

const pathtoswaggerjson = document.getElementById("pathtoswaggerjson").value

А теперь пишем код по получению всех проектов:

new SwaggerClient(pathtoswaggerjson, {requestInterceptor: (req) => {
      req.headers.Authorization = 'Basic base64(user:token)';
      return req;
    }})
        .then(
          client => client.apis.Projects.getAllProjects()
        )
        .then(
          getAllProjectsResult => console.log(getAllProjectsResult.body),
        )

  }

И это все!

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

open -n -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --args --user-data-dir="/tmp/chrome_dev_test" --disable-web-security

Теперь открываю мою форму и вижу в консоли вот такие данные:

This image has an empty alt attribute; its file name is Screenshot-2020-10-01-at-15.48.51-1024x469.png

Это все мои проекты с Jira Cloud.

Мы написали всего лишь несколько строк кода, чтобы получить эти данные.

Вы можете посмотреть все доступные методы вот так:

new SwaggerClient(pathtoswaggerjson, {requestInterceptor: (req) => {
      req.headers.Authorization = 'Basic Basic base64(user:token)';
      return req;
    }})
        .then(
          client => console.log(client.apis)
        )

Если опять откроете форму, то в консоли будет вот такое:

This image has an empty alt attribute; its file name is Screenshot-2020-10-01-at-15.51.41-946x1024.png

Это список всех доступных для вызова методов.

Заключение

Как Вы видите, мы пишем примерно одинаковое количество кода с обертками и сваггером. Тогда зачем использовать сваггер?

  1. Разработчики продукта обновят сваггер файлы для своих API быстрее, чем разработчики оберток допилят их продукт. Кроме того, разработчики оберток совсем могут забросить их продукт. Зачем им тратить свое время на написание кода, который можно получить ничего не делая?
  2. Если Вы используете Сваггер клиента, то Вы можете использовать этого клиента не только для работы с Jira, но и для работы с любым другим продуктом, поддерживающим Сваггер. В этом случае Вы не тратите время на поиск оберток и изучение работы с ними для других продуктов

Поэтому необходимость оберток значительно снизилась после появления Сваггера. Да, имеем смысл использовать обертки, которые дают какие-то преимущества перед генерируемым клиентами Сваггер кодом. Но таких оберток мало. Их нужно еще поискать и не факт, чтоб Вы найдете его для Вашего продукта. По крайней мере такие обертки для продуктов Atlassian мне неизвестны.

Вы можете посмотреть финальный код здесь.

If you have found a spelling error, please, notify us by selecting that text and pressing Ctrl+Enter.

Leave a Reply

%d bloggers like this:

Spelling error report

The following text will be sent to our editors: