Swagger и OpenAPI — в чём разница и как выбрать правильный инструмент
Представьте, что в команде двое разработчиков. Один просит другого «добавить Swagger в проект» — и оба расходятся делать разные вещи. Первый идёт писать аннотации в коде. Второй — настраивать Swagger UI. Оба правы, потому что под одним словом скрываются три разные вещи: стандарт описания API, набор инструментов и интерактивная документация.
Путаница появилась исторически. До 2015 года стандарт описания API назывался Swagger Specification. Потом его передали Linux Foundation и переименовали в OpenAPI Specification — чтобы отвязать от конкретного вендора. Swagger остался названием экосистемы инструментов компании SmartBear. С тех пор OpenAPI — это стандарт, а Swagger Editor, Swagger UI и Swagger Codegen — инструменты для работы с ним.
Но OpenAPI подходит не для всех архитектур. Для событийных систем на Kafka или WebSocket есть AsyncAPI. Для GraphQL-интерфейсов — собственный SDL. Для команд в экосистеме MuleSoft — RAML. А API Blueprint, который ещё несколько лет назад был популярным выбором для простых проектов, с 2019 года фактически не развивается — после того как Oracle поглотила Apiary.
В статье разобрали каждый из форматов, объяснили разницу между подходами design-first и code-first, рассказали, почему в 2018 году от Swagger Codegen отделился форк OpenAPI Generator — и как импортировать OpenAPI-спецификацию в Документерру, чтобы не переписывать эндпоинты вручную. В конце — таблица для быстрого выбора формата и ЧаВо по частым вопросам.