Спецификация OpenAPI

Спецификация OpenAPI - это открытая спецификация, поддерживаемая сообществом в рамках Инициативы OpenAPI, совместный проект с Linux Foundation.

По своему назначению, OpenAPI считается универсальным интерфейсом для взаимодействия пользователей (клиентов) с сервисами (серверами). Это аналогично описаниям интерфейса для программирования более низкого уровня. Если спецификация для определенного сервиса разработана, на её основе можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др. Для этих действий имеется большой набор инструментов для различных языков программирования и платформ.

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

Документы OpenAPI описывают API-сервис и представлены в форматах YAML или JSON. Эти документы могут быть созданы и поддерживаются статически (FirstAPI), или создаваться динамически из приложения (CodeFirst).

Спецификация OpenAPI не требует перезаписи существующих API. Она не требует привязки какого–либо программного обеспечения к сервису - описываемый сервис может даже не принадлежать создателю его описания. Однако требуется, чтобы возможности сервиса были описаны в структуре спецификации OpenAPI. Не все службы могут быть описаны с помощью OpenAPI – эта спецификация не предназначена для охвата всех возможных вариантов API HTTP, но включает поддержку API REST. Спецификация OpenAPI не предписывает конкретный процесс разработки, такой как сначала описание (First-API, Design-First) или сначала код (Code-First).

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

Текущая версия - 3.1.0

Текущая версия спецификации OpenAPI OpenAPI Specification 3.1.0.

Предыдущая версия

Этот репозиторий также содержит все предыдущие версии.

Каждая папка в этом репозитории, такие как examples и schemas, должна содержать папки, относящиеся к текущей и предыдущим версиям спецификации.

Увидеть это в действии

Если вы просто хотите увидеть, как это работает, посмотрите список текущих примеров.

Инструменты и библиотеки

Хотите узнать, как вы можете создать свой собственный инструмент OpenAPI, представить его или иным образом использовать? Проверьте растущий список инструментов.

Участие

Текущий процесс разработки спецификации OpenAPI описан в Руководство по разработке. Разработка следующей версии спецификации OpenAPI руководствуется Техническим руководящим комитетом (TSC). Эта группа коммитеров привносит свой опыт в области API, учитывает отзывы от сообщества и расширяет группу коммитеров при необходимости. Все разработки по будущей спецификации будут выполняться как функции и сливаться в эту ветку. После выпуска будущей спецификации эта ветка будет слита с main.

TSC проводит еженедельные веб-конференции для рассмотрения открытых пулл-реквестов и обсужд

ения открытых вопросов, связанных с развитием спецификации OpenAPI. Участие в еженедельных звонках и запланированных рабочих сессиях открыто для сообщества. Вы можете просмотреть календарь TSC в интернете. Ищите кнопку "Подписаться на календарь" для получения инструкций по подписке.

Инициатива OpenAPI призывает к участию как отдельных лиц, так и компаний. Если вы хотите участвовать в развитии спецификации OpenAPI, рассмотрите возможность выполнения следующих действий:

• Ознакомьтесь с текущей спецификацией. Файл с читаемым человеком markdown является источником истины для спецификации.
• Ознакомьтесь с процессом разработки, чтобы понять, как эволюционирует спецификация.
• Проверьте вопросы и пулл-реквесты, чтобы увидеть, не документировал ли кто-то уже вашу идею или отзыв о спецификации. Вы можете следовать за существующим обсуждением, подписавшись на существующий вопрос или пулл-реквест.
• Подпишитесь на один открытый вопрос в день (или в неделю) в вашем почтовом ящике через CodeTriage.com.
• Создайте вопрос для описания новой проблемы. Если это возможно, предложите решение.

Не все отзывы могут быть учтены, и могут быть веские аргументы за или против изменения, подходящего для спецификации.

Лицензия

Смотрите: Лицензия (Apache-2.0)