Секретные технологии документирования API

Disclamer: Все совпадения случайны. Если вы узнали в этом тексте себя, то это ошибка и ваше больное воображение. Я это все придумал.

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

Есть даже какое-то REST-оподобное API и оно даже умеет возвращать ответы в формате JSON. Документация к API традиционно отсутствует, но заказчик готов ее сделать если мы предоставим шаблон на который можно ориентироваться. Ок, выбор очевиден. Нужно использовать формат OpenAPI, который отлично документирован и позволяет создавать спецификации любой сложности. А разухабистый тулинг вокруг него позволяет генерировать уже готовую и +- рабочую реализацию, что сильно сокращает время на разработку. Это и было озвучено менеджеру, который через некоторое время вернулся (а я надеюсь, что он хотябы попытался спросить) с ответом: я боюсь, что такими технологиями заказчик не владеет. “такими ТЕХНОЛОГИЯМИ”, серьезно? Это же почти как на ассемблере под STM32 писать да? Спецификацию в формате OpenAPI способен написать джуниор бизнес-аналитик, не говоря уже о разработчике. Тем более речь не идет о каком-то дополнительном проектировании. Нужно было всего лишь описать то, что уже работает. Далее я был готов подключится и помочь в перепроектировании текущей реализации если бы это вообще потребовалось. Но нет. Такие сложнейшие технологии видимо оказались недосягаемы для заказчика.

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

openapi: 3.0.3
info:
  title: BaseTemplate
  version: '1.0'
  description: Base API template
  contact:
    name: API Creator
servers:
  - url: 'http://localhost:3000'
tags:
  - name: Main
    description: Main operations
paths:
  /method_example:
    get:
      summary: Your GET endpoint
      tags:
        - Main
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelExample'
      operationId: get-method_example
      description: Method example
components:
  schemas:
    ModelExample:
      title: ModelExample
      type: object
      properties:
        id:
          type: string
      x-tags:
        - Main

Выглядит страшно? Если да, то можно взять какую-нибудь утилиту, которая позволит красиво это все отображать. Я пользуюсь бесплатной версией Stoplight Studio, и она покрывает все мои нужды. В ней даже можно создавать такие спеки с нуля вообще не погружаясь в сам формат OpenAPI. Т.е. это настолько просто, что даже стыдно называть это словом “технологии”. Вы когда пишите в простигосподи ворде каком-нибудь тестовый документ, вы же не считаете это какими-то запредельными технологиями? Ну я надеюсь…

Даже очень крупные компании грешат применением всяких вордов при написании спецификаций. При этом всем накласть на то, что это не версионируется нормально, отследить изменения практически невозможно, навигации из коробки нет и она в лучшем случае сделана в виде блока “Содержание”, которое опять же нужно поддерживать при внесении изменений. Зачем вам этот ад? У вас так много свободного времени? Перейдите уже на что-то более благообразное вроде OpenAPI или чего-то подобного (а альтернативы есть). Сэкономьте время людям которые будут с вами интегрироваться и свои деньги за эту интеграцию.

Полезные ссылки:

openapi архитектура