Исходная ссылка：https://document360.com/blog/open-api

Что такое OpenAPI?

По данным SmartBear (материнская компания Swagger):

«Спецификация OpenAPI (OAS) определяет стандартный, независимый от языка интерфейс для RESTful API, который позволяет людям и компьютерам обнаруживать и понимать сервисы без доступа к исходному коду, документации или проверки сетевого трафика».

Это что-то вроде глотка. Разобьем описание SmartBear на более мелкие части:

1. «...определяет стандарт...»:

Спецификация OpenAPI определяет API изструктура, также описанная API。

2. «...Независимый от языка интерфейс для RESTful API...»:

• REST API использует протокол HTTP для передачи данных. Протокол позволяет использовать для взаимодействия платформы и системы, написанные на разных языках программирования.
• OpenAPI Только процесс RESTful API, а не другие типы API。

3. «...способность позволить людям и компьютерам обнаруживать и понимать сервисы...»:

• Люди могут напрямую API из генерации определений OAS из документации для чтения.
• На основании определения API клиент знает, как отправлять запросы и как сервер API отвечает на эти запросы.

4. «…Нет необходимости обращаться к исходному коду, документации или проверять сетевой трафик».

В OpenAPI клиентское приложение и сервер API разделены. Определение API службы определяет, как клиенты взаимодействуют с ней, не требуя от клиентов чтения ее исходного кода.

Таким образом, OpenAPI — это спецификация RESTful API, описывающая API, соответствующие архитектуре RESTful. Спецификации предоставляют интерфейс для людей и компьютеров, позволяющий понять API и способы взаимодействия с ним.

История OpenAPI

Истоки OpenAPI восходят к 2009 году, когда инженер компании Wordnik Тони Тэм создал спецификацию (тогда известную как Swagger) для описания JSON API онлайн-словаря Wordnik.

В течение следующих нескольких лет Тони сделал несколько итераций Swagger. Однако распространение спецификации Swagger 2.0 возросло и привело к созданию инструментов для анализа спецификации.

В 2015 году SmartBear приобрела Swagger. SmartBear — компания, которая в настоящее время владеет Swagger. Спецификация Swagger была переименована в OpenAPI, чтобы отразить новую инициативу OpenAPI. Вот почему «Swagger» путают со стандартом «OpenAPI».

В то время группа компаний осознала, что отрасли нужен нейтральный к поставщикам и стандартизированный способ описания API. От промышленности требуется предоставлять «лучшие практики» отрасли и контролировать обновления OpenAPI.

Компании учредили Инициативу OpenAPI в рамках Linux Foundation, которая будет служить программой управления, которая поддерживает стандарты OpenAPI и предоставляет практические рекомендации. В число компаний-основателей инициативы OpenAPI входят CapitalOne, PayPal, SmartBear, IBM, 3Scale, Google, Apigee, Intuit, Microsoft и Restlet. С тех пор количество компаний, участвующих в инициативе, значительно выросло.

Технический руководящий комитет теперь управляет OpenAPI и продолжает выпускать новые версии на основе отзывов сообщества.

Почему OpenAPI является популярным стандартом?

Существует несколько спецификаций, которые можно использовать для описания RESTful API。OpenAPI — одна из наиболее известных и широко используемых спецификаций. Мы представим его позже Преимущества OpenAPI и Недостатки и Другие форматы сравнения. хотя OpenAPI можно считать отраслевым стандартом, но в конечном итоге компании часто выбирают формат, который лучше всего соответствует потребностям их бизнеса.

Итак, если для описания REST API можно использовать несколько форматов, почему OpenAPI такой особенный? Ключевым фактором популярности OpenAPI является скорость его внедрения. Более широкое внедрение приводит к большей поддержке сообщества, мощным инструментам и более эффективному управлению.

Компании могут использовать его из-за его мобильности и простоты. OpenAPI спецификация. OpenAPI да “и Независимый от языкаиз”,и определяет общий язык для взаимодействия клиент-сервер. Он обладает высокой совместимостью с различными языками программирования и системами. OpenAPI OpenAPI сообществом.

Еще один популярный формат да РАМЛ, это своего рода API Язык моделирования с акцентом на API определение и дизайн (хотя вы можете использовать OpenAPI дизайн API ）。RAML Функция может выглядеть меньше, чем OpenAPI Более превосходный. Его преимущество заключается в иерархической поддержке наследования модели данных. Однако, РАМЛ уровень принятия не так хорош, как OpenAPI широко. Хотя RAML Существует специализированное сообщество, но оно пользуется меньшей поддержкой сообщества. РАМЛ Инструменты есть, но есть признаки того, что в последней версии отсутствует необходимая поддержка.

Кроме RAML,API Blueprint да OpenAPI Другая альтернатива. API Blueprint Сосредоточьтесь на четкой документации и полагайтесь на markdown Формат, и не да-как OpenAPI Такой же JSON или нравится OpenAPI и RAMLТакой же ЯМЛ. Из-за низкой распространенности API Blueprint не хватает поддержки сообщества и мощных инструментов. Воля API Blueprint интегрировано во всю вашу API Жизненный цикл Сложность, потому что это основной фокус документа.

Подводя итог, OpenAPI да Описание API Самый популярный стандарт. Несмотря на свои недостатки, OpenAPI Уровень внедрения, вероятно, будет расти. Другие типы спецификаций. Долгосрочная осуществимость неясна.

Как OpenAPI определяет API?

Представьте, что вы читаете традиционный авторитетный документ в формате Microsoft Word (.docx). Этот традиционный документ спецификации предоставляет общую информацию о системе и описывает ее компоненты и взаимодействие с другими системами.

Традиционные нормы изструктуры имеют тенденцию меняться. изображение OpenAPI Такая спецификация API, его строгая структура. Если спецификация API соответствует другому формату, например RAML или API Blueprint,тогда документ будет следовать этому Форматструктура。

Возвращаясь к тому, как OpenAPI определяет API, вы часто будете слышать, как слова «спецификация» и «определение» используются как синонимы. Спецификация API «определяет» API. Читая спецификацию API, вы узнаете о типах запросов, которые вы можете отправлять, и о том, какие ответы вы можете ожидать получить от API. Кроме того, спецификация описывает доступные параметры, влияющие на возвращаемую информацию. Как и в случае с традиционными спецификациями, вы узнаете о системе, ее компонентах и ​​о том, как они взаимодействуют.

традиционные нормы и API Еще одно различие между спецификациями — API. Норма да динамична из. в любое время API При изменении базового исходного кода документация обновляется. Всякий раз, когда в системе происходят изменения, традиционные документы спецификации необходимо обновлять вручную. Word документ.

Формат OpenAPI

В понимании OpenAPI Спецификацию изструктуры, которую необходимо знать заранее OpenAPI Формат документа. с традиционным Word Различные характеристики записи из, Формат OpenAPIда JSON. Хотя обсуждение JSON Нюансы выходят за рамки этой статьи в блоге, но их можно описать. JSON Думайте об этом как о способе представления данных API в виде ключевых значений.

Например, в традиционной спецификации вы можете использовать стиль заголовка на титульной странице для написания названия спецификации (включая имя системы). С другой стороны, чтобы написать заголовок спецификации OpenAPI, вам нужно написать заголовок в виде пары ключ-значение JSON.

Теперь подумайте о API вся информация. Его методы, операции, реакции и т. д. Представьте себе все эти свойства как OpenAP Iструктура Записыватьсуществоватьсерия этогоизключевое значениеверносередина。

Примечание: хотя JSON да OpenAP Стандартный формат для I, но можно использовать и более простые. YAML (YAML не является языком разметки из аббревиатуры) для представления OpenAPI。

• Уведомление: Однако JSON да OpenAPI стандартного формата, но также может быть OpenAPI Представлено как более простое из YAML（YAML ain’t markup language (аббревиатура).

тип данных

как JSON Объект, OpenAPI Более широкая поддержка спецификации из модели JSON, определенной в спецификации из типа. данных。базовыйтип данные включают в себя целые числа, числа, логические значения и строки. Вы можете использовать атрибут модификатора format объявить тип формат данных. Например, вы можете объявить целое число как int32 илиi nt64 формате, объявите число как float или double,или объявляет строку как binary、 data、 date-timeили password Формат. OpenAPI Также поддерживается более широкий диапазон JSON В спецификации она определена как модель «верно слон».

важныйизда Обратите внимание на,JSON да REST API Основной формат, используемый для отправки и получения информации.

структура

На данный момент мы узнали:

• OpenAPI Норма даа JSON объект.
• API из атрибута да набор ключевых значений верно.
• Значение да состоит из более широкого диапазона из JSON Нормативное определение изтип данных。

Обсудить существование OpenAPI изструктура. Как упоминалось ранее, OpenAPI Документация строго структуризирована. Связанные ключевые значения верно группируются в виде верного символа или массива символов верно. OpenAPI Объекты высокого уровня спецификации подобны главам традиционного документа спецификации.

Нижний имеет загнутую часть из Шаблон OpenAPI,Показывает общую структуру. Каждая часть имеет атрибут или значение ключа, верно,предоставить информацию о API метаданные.

OpenAPI Верхний уровень, состоящий из первого набора скобок. { } представление, называемое «объектом документа», поскольку оно содержит все OpenAPI. свойство.

Хотя OpenAPI Документация должна соответствовать базовой структуре, но OpenAPI Обеспечивает некоторую гибкость. Некоторые дополнительные детали необходимы, другие — нет. ты заметишь разницу API из OpenAPI Технические характеристики могут выглядеть немного иначе.

Документация OpenAPI может содержать следующие компоненты:

• Openapi： Обязательное поле, определенное API из OpenAPI Каноническая версия. Инструмент использовать номер версии для анализа OpenAPI Спецификации для создания документации, например.
• Info： Содержит метаданные и обязательные поля. Инструменты могут использовать метаданные по-разному.
• Servers： Массив значков серверов. Каждый значок сервера содержит подробную информацию о подключении к серверу. Значок «Верно» содержит URL-адрес хоста сервера и описание сервера.
• Paths： Обязательный объект, содержащий соответствующие пути к каждой конечной точке API. Данный путь доступен для и API Интерактивные операции, такие как POST、GET、PUT или DELETE。
• Components： Схема безопасности, содержащая тело запроса, модель ответа. Эта часть содержит некоторые части спецификации (например, значок пути). \$ref Ссылка на этикетку.
• Security： Запрос авторизации оператора типа схемы безопасности и объекта безопасности, как и глобальное определение, также может быть точно указан для переопределения (переопределения схемы безопасности).
• Tags： Содержит метаданные из объектов. Спецификации инструментов синтаксического анализа могут использовать этот объект. Например, вы можете указать, что вам нужно для каждого из них. API ресурссуществовать API Документы отображаются в порядке (а не в алфавитном порядке).
• ExternalDocs： Содержит ссылки на дополнительную документацию. Вы можете добавить эту ссылку в руководство пользователя.

модель

существовать API Внизу документа обычно есть раздел модели, который соответствует API Описание комплектующей в определении измодель.

Этот раздел представляет собой краткий справочник, когда читателю необходимо просмотреть общие API в более широком контексте (а не в конкретной операции). модельда содержит свойства/метаданные изобъекта.

Следующие да Swagger Petstore измодельчасть,Показывает в пределах спецификацииизмодель。Order даамодель,Разместите заказ на домашних животных от имени Swagger Petstore. Каждый заказ имеет свои метаданные,включая егоID、Дата отправкии Заказсостояние。

Преимущества OpenAPI

OpenAPI имеет следующие преимущества:

• Очистить документацию?– OpenAPI Он известен своей легкостью чтения людьми и компьютерами.
• Независимый от языка?– Клиент может взаимодействовать с сервером API, не зная реализации сервера. другие форматы, такие как API Blueprint,Требуется сторонний код на сервере,И никакого кода для этого вам не предоставлено.
• управление?– OpenAPI Инициативное обслуживание OpenAPI стандартам и проводится лидерами отрасли.
• Широкое распространение?– OpenAPI да Описание REST API Самый популярный формат. Область его применения указывает OpenAPI да долго из. картина API Blueprint Такие нормы страдают от отсутствия принятия.
• Мощные инструменты?– Как наиболее широко поддерживаемый из существующих форматов, в настоящее время используется большим количеством инструментов. OpenAPI Сгенерируйте документацию, протестируйте ожидание. Отсутствие других характеристик. OpenAPI Поддержка и Обслуживание инструментов.

Недостатки OpenAPI

Каждый тип спецификации имеет свои преимущества и недостатки. существования Здесь мы сосредоточимся на OpenAPI это самая близкая внеконкуренция RAML Недостатки по сравнению с из.

Не очень полезно для проектирования и планирования API.

Вы можете взять «Стандарты прежде всего»изметод дизайна, основанный на OpenAPI из API. Этот подход предполагает написание вручную API из OpenAPI Инструмент спецификации илииспользоватьдизайн. использовать этот метод, который вы проектируете API из Норм,Однаконазадсуществоватьстроить API Рассматривайте спецификацию как «контракт». «Стандарты» прежде всего»Напротивизда,использовать OpenAPI Создает документацию, но не использует ее в качестве инструмента проектирования.

Хотя«Стандарты прежде Метод «все» имеет много преимуществ, но OpenAPI Обычно нетсуществовать API появляются раньше развития.

RAML Изуровневая структура может быть более подходящей в качестве инструмента планирования дизайна. Следовательно, РАМЛ наверное, лучше, чем REST Дополнительная поддержка «Стандарты прежде всего» из метода. В конечном итоге РАМЛ продается с определенной целью «Моделирование данных» и “API описывать" Инструменты и Swagger Тогда только последнее. В следующем разделе обсуждается более подробно RAML из иерархической модели.

неиерархический

OpenAPI и RAML ждать API Одной из основных концепций стандарта определения является возможность создавать объекты данных и связывать их вместе. OpenAPI использоватьмодель для достижения этой цели и поддержки JSON встроенного типа данные. RAMLIспользовать Система типов для сохранения связанных свойств и облегчения повторного использования между спецификациями. Он также поддерживает OpenAPI такой жевстроенного типа данных。

OpenAPI Реальной структуры уровня нет. Чего ты хочешь от описания тебя? API изуровеньструктурасерединачто получить？В идеале,Вы хотите иметь модель данных, связанную с вашей системой,Эта система должна:

• Легко читать/понимать
• Позволяет использовать наследование существования для определения отношений между моделями данных.
• Уменьшите дублирование общих атрибутов
• Максимизируйте повторное использование кода

и REST По сравнению с РАМЛ Система типов делает ее более иерархической. в соответствии с RAML существоватьGitHub Readme на из, RAML использовать "Тип ресурса и характеристики свернуты RESTful API дизайн в из повторяется и продвигается API внутренний и поперек API из Консистенция. "

Далее мы обсудим более подробно RAML изсистема типов。

Наследование модели данных не поддерживается.

RAML неожиданно типы слонов могут наследовать другие типы слонов. хотя OpenAPI модель может «ссылаться» на другую модель, но это не так. RAML Такой способ существования технически поддерживает наследование. Я говорю «технически», потому что вы можете использовать ссылку на модель (тег \$ref), чтобы связать одну модель с другой.

и RAML Затем сделайте еще один шаг вперед. Вы можете построить связи между моделями данных и избежать дублирования общих атрибутов. использовать OpenAPI, модель не будет похожа RAML Таким образом, они связаны друг с другом иерархическим образом. РАМЛ Типы имеют «реальное» наследование, где можно существовать из отношений «родитель-потомок» между моделями данных.

Не «визуальный» инструмент

RAML OpenAPI более интуитивно понятен и легче читается. Вы можете легко увидеть связи между типами и их общими свойствами.

Будучи более наглядным из инструментов, RAML обеспечивает такие функции, как моделирование ответов сервера, консоль API и долгосрочное планирование. Это также может быть полезно при прогнозировании и планировании будущих улучшений API.

Отсутствие поддержки других архитектур.

OpenAPI могу только описать RESTful API。RAML Имеет поддержку, кроме REST Дополнительная поддержка других архитектур, таких как RPC или SOAP, пока они используют HTTP протокол. РАМЛ Гибкость позволяет использовать его в дополнение к REST из Архитектураиз Инструмент документации.

Пример OpenAPI — Swagger Petstore

изучать OpenAPI Лучший способ – практика. Некоторые инструменты позволяют редактировать OpenAPI Спецификация и последующая генерация API документ.Swagger Petstore да OpenAPI Документ из примера.

SwaggerUI даодин для разбора API Определите инструмент для создания документации. SwaggerUI Существуют браузерные редакторы (показаны ниже). Вы можете попробовать это здесь SwaggerUI Редактор：https://editor.swagger.io/

существуют На левой панели вы можете увидеть YAML Формат OpenAPI спецификация. Когда вы действительно вносите изменения в спецификацию, эти изменения будут созданы непосредственно из правой панели документа. OpenAPI Спецификация (Сваггер Petstore) генерировать из Swagger Например, изменение пути к описанию приведет к появлению документа. Документация Swagger обновляется и отображает новые изменения.

Если вы просмотрите Swagger из OpenAPI спецификациялевая сторона,Вы увидите все части, описанные в этой статье.,включатьopenapi, info, servers, paths, components, tagsждать。

Когда ты делаешь опечатку из OpenAPI структураили При вводе недопустимого контента Swagger Будет сообщено об ошибке. Сваггер из Обработка ошибок подтверждает, что вы должны следовать OpenAPI Формат для правильного отображения концепций документа. Как только вы познакомитесь со Swagger Petstore, вы можете добавить другие из API из Характеристики вклеены в Swagger редактор, чтобы посмотреть, как существует информация SwaggerUI отображается в.

В общем, Сваггер Редактор да Научитесь писать API Определение и то, как инструмент анализирует спецификацию для создания документации в соответствии с хорошим подходом.

дальнейшее чтение

Чтобы узнать больше об OpenAPI Стандарт, пожалуйста, прочитайте официальный SmartBear из OpenAPI документ：https://swagger.io/specification

Более API Управление и API Контент, связанный с полным жизненным циклом, может существоватьiiz Notion Проверять,Я буду продолжать обновлять：API Полная информация по управлению жизненным циклом