Однажды я искал предложения о работе в LinkedIn и увидел, что для бэкенд-инженеров опыт работы с OpenAPI и Swagger является плюсом. Я слышал этот термин один или два раза, но никогда раньше не проверял его сам. Итак, я просмотрел веб-сайт и нашел то, что кажется приветствующей инициативой для моего любимого способа проектирования программного обеспечения: разработка, ориентированная на дизайн. Наконец-то я нашел свой дом.

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

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

В таком языке, как Rust, владение и заимствование лежат в его основе. Так же и жизни. При написании бэкэндов на Rust я всегда думал о том, какие функции нужно заимствовать, а какие — владеть (а также о том, чтобы не возвращать ссылки, если я не знаю, что у них есть действительное время жизни). С другой стороны, я могу свободно возвращать ссылки в Go. Я уже делал это в системе студенческих журналов, и все работает так, как и ожидалось. На обоих этих языках я всегда включал их концепции в свой дизайн настолько, насколько мог, чтобы обеспечить беспрепятственный опыт разработчика, когда я действительно сажусь и пишу код.

Найдя веб-сайт инициативы OpenAPI и ознакомившись с их основами написания документа OpenAPI, я был удивлен и потерял дар речи. То, что я увидел, было стандартизированным способом разработки серверных API, написанных на YAML, с полной документацией и руководством по стилю. Осознание того, что такая вещь существует, было поистине замечательным чувством. Теперь я, наконец, могу проектировать свои API таким образом, чтобы их было легко понять и написать.

Ниже приведен пример документа OpenAPI 3, написанного на YAML, о простом API «Hello, World»:

openapi: 3.0.0
info:
  title: MinimaPI
  description: A minimal API specification written in OpenAPI.
  version: 1
paths:
  /greet:
    get:
      summary: Greet the user
      description: Return a nice greeeting to the client.
      responses:
        "200":
          description: The backend is working; greeting on its way.
          content:
            text/plain:
              schema:
                type: string
                example: Hello, World!

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

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

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