Спецификация интерфейса OpenAPI: основное руководство по созданию эффективных сервисов API!

Спецификация интерфейса OpenAPI

OpenAPI — это стандартный способ описания HTTP API. Сегодня поговорим о его спецификации интерфейса ( спецификация OpenAPI (китайская версия) )~

Спецификация номера версии OpenAPI

Номер версии OpenAPI определяется в формате major.minor.patch, например 3.1.2.

major: указывает основную версию
минор: указывает минорную версию
patch: указывает патч в минорной версии

Спецификация формата OpenAPI

OpenAPI может использовать формат JSON или YAML, а поля чувствительны к регистру:

Пример JSON

YAML-пример

Спецификация структуры документа OpenAPI

Документ OpenAPI может быть одним документом или несколькими документами, на усмотрение вашей команды. В последнем случае ключевое слово $ref необходимо использовать в ссылочных объектах и объектах схемы.

Что касается именования документа, то рекомендуется называть его openapi.json или openapi.yaml.

Спецификация типа данных OpenAPI

Тип данных OpenAPI должен соответствовать спецификации проекта спецификации схемы JSON 2020-12.

Адрес спецификации схемы JSON: draft-bhutton-json-schema-00

Спецификация формата расширенного текста OpenAPI

Поле описания OpenAPI поддерживает формат уценки CommonMark, поэтому при использовании форматированного текста в OpenAPI формат должен соответствовать формату уценки CommonMark.

Объект OpenAPI

Информационный объект

Метаданные, описывающие API

Контактный объект

Контактная информация API

Объект сервера

Информация об объекте сервера API

может быть сервер

Также может быть несколько серверов

Компоненты Объект

Повторно используемые объекты компонентов для API

Пути объекта

Объект, описывающий URL API

Объект элемента пути

Объект с операциями, доступными по одному пути

Объект операции

Объект для одной операции API на пути

Объект внешней документации

расширить внешние ресурсы

Параметр Объект

объект параметра

Объект тела запроса

Объект одного запроса Body

Объект ответов

API возвращает объект ответа

Объект заголовка

объект заголовка запроса