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 для людей
- Спецификация OpenAPI для роботов
- WYSIWYG-редактор yaml-спецификации OpenAPI
- Много полезных утилит для работы с OpenAPI