Api спецификация что это: Знакомство со спецификациями OpenAPI и Swagger

Знакомство со спецификациями OpenAPI и Swagger

Edit me

OpenAPI является спецификацией для описания REST API. Можно рассматривать спецификацию OpenAPI как спецификацию DITA. В DITA существуют определенные элементы XML, используемые для определения компонентов справки, а также требуемый порядок и иерархия для этих элементов. Различные инструменты могут читать DITA и создавать веб-сайт документации на основе информации.

В OpenAPI вместо XML существует набор объектов JSON с определенной схемой, которая определяет их наименование, порядок и содержимое. Этот файл JSON (часто выражается в YAML вместо JSON) описывает каждую часть API. Описывая API в стандартном формате, инструменты публикации могут программно анализировать информацию об API и отображать каждый компонент в стилизованном интерактивном виде.

Tip: Если есть желание сразу перейти к пошаговому справочнику по созданию документации в спецификации OpenAPI, см. Обзор руководства OpenAPI.

Взгляд на спецификацию OpenAPI

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

Официальное описание спецификации OpenAPI доступно в репозитории Github. Элементы OpenAPI — это paths, parameters, responses и security. Каждый из этих элементов является объектом JSON, который содержит свойства и массивы.

В спецификации OpenAPI ваши конечные точки это paths. Конечная точка /pet, в спецификации OpenAPI может выглядеть следующим образом:

paths:
    /pets:
        get:
            summary: List all pets
            operationId: listPets
            tags:
                - pets
            parameters:
                - name: limit
                in: query
                description: How many items to return at one time (max 100)
                required: false
                schema:
                    type: integer
                    format: int32
            responses:
                '200':
                description: An paged array of pets
                headers:
                    x-next:
                        description: A link to the next page of responses
                        schema:
                            type: string
                content:
                    application/json:    
                        schema:
                            $ref: "#/components/schemas/Pets"
            default:
                description: unexpected error
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/Error"

Это формат YAML, взят из Swagger PetStore

Вот что значат объекты в этом коде:

• /pets — конечна точка path;
• get — HTTP метод;
• parameters — список параметров конечной точки;
• responses — список ответов на запрос
• 200 — HTTP код статуса
• $ref является ссылкой на другую часть реализации, где определяется ответ (в components). OpenAPI имеет много $ref ссылок, подобных этой, чтобы сохранить код в чистоте и облегчить его повторное использование.

Note: Может потребоваться некоторое время, чтобы понять спецификацию OpenAPI. Возьмем пару недель и несколько примеров спецификации, чтобы посмотреть, особенно в контексте фактического API. Спецификация OpenAPI достаточно общая, чтобы описать почти каждый API REST, поэтому некоторые части могут быть более применимыми, чем другие.

Проверка спецификации

При создании спецификации OpenAPI, вместо того, чтобы работать в текстовом редакторе, можно написать свой код в редакторе Swagger. Редактор Swagger динамически проверяет контент, чтобы определить, является ли созданная спецификация валидной.

Если допустить ошибку при написании кода в редакторе Swagger, можно быстро исправить ее, прежде чем продолжить, вместо того, чтобы ждать запуска сборки и устранять ошибки.

Для формата спецификации у нас есть выбор работы JSON или YAML. Пример кода выше находится в YAML. У YAML официальное определение: «YAML не является языком разметки», что означает, что в YAML нет тегов разметки <>, как в других языках разметки, таких как XML.

YAML зависим от пробелов и двоеточий, устанавливающих синтаксис объекта. Такое пространственно-чувствительное форматирование делает код более понятным для человека. Однако, иногда могут возникнуть сложности с расстановкой правильных интервалов.

Автоматическая генерация файла OpenAPI из аннотаций кода

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

Swagger предлагает множество библиотек, которые можно добавлять в свой программный код для создания документа в спецификации. Эти библиотеки Swagger анализируют аннотации, которые добавляют разработчики, и генерируют документ в спецификации OpenAPI. Эти библиотеки считаются частью проекта Swagger Codegen. Методы аннотации различаются в зависимости от языка программирования. Например, вот справочник по аннотированию кода с помощью Swagger для Scalatra. Для получения дополнительной информации о Codegen см. Сравнение инструментов автоматического генерирования кода API для Swagger по API Evangelist. Дополнительные инструменты и библиотеки см. В разделах «Интеграции и инструменты Swagger» и «Интеграция с открытым исходным кодом».

Хотя этот подход и «автоматизирует» генерацию спецификации, нужно еще понимать, какие аннотации добавить и как их добавить (этот процесс не слишком отличается от комментариев и аннотаций Javadoc). Затем нужно написать контент для каждого из значений аннотации (описывая конечную точку, параметры и т. Д.).

Короче говоря, поработать все нужно — автоматизированная часть заставляет библиотеки Codegen генерировать определения модели и действительный документ, который соответствует схеме OpenAPI. Тем не менее, многие разработчики взволнованы этим подходом, потому что он предлагает способ генерировать документацию из аннотаций кода, что разработчики годами делали с другими языками программирования, такими как Java (используя Javadoc) или C ++ (используя Doxygen). Они обычно считают, что генерация документации из кода приводит к меньшему отклонению документации. Документы, будут оставаться актуальными, если будут тесно связан с кодом.

Если идти по этому пути, нужно убедиться, что есть доступ к исходному коду для внесения изменений в аннотации. В противном случае разработчики будут писать документацию (что может и хорошо, но часто приводит к плохим результатам).

Подход: разработка по спецификации

Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация — не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».

Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.

Другими словами, разработчики обращаются к спецификации, чтобы увидеть, как должны называться имена параметров, каковы должны быть ответы и так далее. После того, как этот «контракт» или «план» был принят, Стоу говорит, можно поместить аннотации в свой код (при желании), чтобы сгенерировать документ спецификации более автоматизированным способом. Но не стоит кодировать без предварительной спецификации.

Слишком часто команды разработчиков быстро переходят к кодированию конечных точек API, параметров и ответов, без пользовательского тестирования или исследования, соответствует ли API тому, что хотят пользователи. Поскольку управление версиями API-интерфейсов чрезвычайно сложно (необходимо поддерживать каждую новую версию в дальнейшем с полной обратной совместимостью с предыдущими версиями), есть желание избежать подхода «быстрый сбой», который так часто отмечают agile энтузиасты. Нет ничего хуже, чем выпустить новую версию вашего API, которая делает недействительными конечные точки или параметры, используемые в предыдущих выпусках. Постоянное версионирование в API может стать кошмаром документации.

Компания Smartbear, которая делает SwaggerHub (платформу для совместной работы команд над спецификациями API Swagger), говорит, что теперь для команд чаще встречается ручное написание спецификации, а не встраивание аннотаций исходного кода в программный код для автоматической генерации. Подход “spec-first development” в первую очередь помогает работать документации среди большего количества членов команды, нежели только инженеров. Определение спецификации перед кодированием также помогает командам создавать лучшие API.

Даже до создания API спецификация может генерировать ложный ответ, добавляя определения ответа в спецификацию. Мок-сервер генерирует ответ, который выглядит так, как будто он исходит от реального сервера, но это просто предопределенный ответ в коде, и кажется динамичным для пользователя.

Роль технического писателя в спецификации

В большинстве проектов Тома Джонсона разработчики были не очень хорошо знакомы с Swagger или OpenAPI, поэтому он обычно создавал документ спецификации OpenAPI вручную. Кроме того, он часто не имел доступа к исходному коду, и для разработчиков английский язык был не родным. Документация была для них сложным делом.

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

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

Визуализация спецификации OpenAPI с помощью Swagger UI

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

Наиболее распространенным инструментом, используемым для анализа спецификации OpenAPI, является Swagger UI. (Помните, что «Swagger» относится к инструментам API, тогда как «OpenAPI» относится к независимой от поставщика спецификации, не зависящей от инструмента.) После загрузки пользовательского интерфейса Swagger его довольно легко настроить с помощью собственного файла спецификации. Руководство по настройке Swagger UI есть в этом разделе.

Код пользовательского интерфейса Swagger генерирует экран, который выглядит следующим образом:

На изображении видно, как Swagger отображает спецификацию Open API

Можно ознакомиться с примером интеграции Swagger UI с примером API сервиса погоды, использованным в качестве примера курса.

Некоторые дизайнеры критикуют выпадающие списки Swagger UI как устаревшие. В то же время разработчики считают одностраничную модель привлекательной и способной уменьшать или увеличивать детали. Объединяя все конечные точки на одной странице в одном представлении, пользователи могут сразу увидеть весь API. Такое отображение дает пользователям представление в целом, что помогает уменьшить сложность и позволяет им начать. Во многих отношениях отображение Swagger UI является кратким справочным руководством по API.

👨‍💻 Практическое занятие: Исследуем API PetStore в Swagger UI

Давайте познакомимся с пользовательским интерфейсом Swagger, используя Petstore.

• Переходим по ссылке Swagger Pet Store Demo

Как и в большинстве основанных на Swagger’е инструментов, в интерфейсе Swagger есть кнопка «Try it out». Для работы необходима авторизация в Swagger. Авторизация по нажатии на кнопку

Authorize, в появившемся окне нужно вставить корректную информацию. При желании авторизоваться можно добавив любой номер в поле api_key и нажав Authorize. Окно авторизации Petstore предназначено только для демонстрации, так что окно можно просто закрыть.

Окно авторизации в Swagger UIКнопка `Try it out` в Swagger UIВыполнение примера Petstore запроса

Swagger UI отправляет запрос и показывает отправленный curl. В примере был отправлен curl:

curl -X POST "https://petstore.swagger.io/v2/pet" -H "accept: application/xml" -H "Content-Type: application/json" -d "{ \"id\": 1000, \"category\": { \"id\": 0, \"name\": \"string\" }, \"name\": \"Bentley\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"available\"}"

Обратите внимание, что с параметром -d (data) параметр тела запроса экранируется и добавляется непосредственно в команду curl, а не загружается из файла (как описано в Общих командах curl, связанных с REST).

В разделе “Ответы” Swagger UI выдает ответ сервера. По умолчанию ответ возвращает XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <Pet>
    <category>
      <id>0</id>
      <name>string</name>
    </category>
    <id>1000</id>
    <name>Bentley</name>
    <photoUrls>
      <photoUrl>string</photoUrl>
    </photoUrls>
    <status>available</status>
    <tags>
      <tag>
        <id>0</id>
        <name>string</name>
      </tag>
    </tags>
  </Pet>

Если выбрать в выпадающем списке “Response content type” JSON, то в ответе вернется JSON вместо XML.

“Petstore” — является действующим API, питомец фактически создан. Для забавы развернем конечную точку GET / pet / {petId}, нажимаем

Try it out, вводим id питомца, который использовали в предыдущей операции, а затем выполняем запрос. В ответе видим имя питомца, которое совпадает с тем, что ввели в предыдущем примере.

Другие инструменты визуализации

Помимо Swagger UI есть и другие инструменты, которые могут анализировать нашу документацию OpenAPI. Вот список из нескольких инструментов: Restlet Studio, Apiary, Apigee, Lucybot, Gelato, Readme.io, swagger2postman, отзывчивую тему swagger-ui, Postman Run Buttons и многое другое.

Кастомизация Swagger UI

Swagger UI можно настроить по своему, чтобы вывод информации не выглядел однообразно: можно настроить цвета интерфейса Swagger, добавить собственный логотип, добавить других пользовательских стилей. Можно интегрировать Bootstrap, чтобы получить модальные окна, где пользователи могут генерировать свои коды авторизации. Можно даже добавить функции сворачивания/разворачивания в элементе description, чтобы предоставить больше информации пользователям.

Однако, помимо этих простых модификаций, потребуется немного мастерства веб-разработчика, чтобы существенно изменить отображение пользовательского интерфейса Swagger. Возможно, понадобятся навыки веб-разработки.

Недостатки OpenAPI и Swagger UI

Несмотря на то, что Swagger обладает интерактивными возможностями апеллировать к желаниям пользователей «дай мне попробовать», у Swagger и OpenAPI есть некоторые недостатки:

• Информация только о ссылке: Во-первых, спецификация OpenAPI и выходные данные Swagger UI охватывают только документацию ссылки. OpenAPI предоставляет основу каждой конечной точки: описание, параметры, пример запроса и ответа. OpenAPI не содержит места для описания начала работы, информации о том, как получить ключи API, как запустить пример приложения, информацию об ограничениях скорости или о сотне других деталей, которые находятся в гайдах для разработчиков. Поэтому, несмотря на то, что есть этот крутой интерактивный инструмент, позволяющий пользователям исследовать и изучать наш API, мы все равно должны предоставить руководство пользователя. По аналогии, вывод Javadoc или Doxygen для основанной на библиотеке API не научит пользователей, как на самом деле использовать наш API. Нам все еще нужно описать сценарии использования класса или метода, объяснить, как настроить код, что делать с ответом, как устранить неполадки и т.д. Короче говоря, писать реальные справочные и пошаговые руководства.
• Избыточность / дублирование информации: В OpenAPI потенциально есть два места, где описываются конечные точки и параметры (описание ссылки Swagger UI и руководство пользователя), и нужно либо синхронизировать их, встроить одно в другое, или иным образом указать связь между ними. Подробнее разберемся в разделе Интеграция Swagger с собственной документацией.
• Сложность рабочего процесса API: Сложность API также может создать ограничение в Swagger. Питер Грюнбаум, опубликовавший несколько учебных пособий по документированию API для Udemy, говорит, что автоматизированные инструменты, такие как Swagger, работают лучше всего для простых API. Если есть конечные точки, которые имеют сложные взаимозависимости и требуют специальных рабочих процессов настройки или другой не интуитивной обработки, простой характер пробного интерфейса Swagger может, вероятно, заставить пользователей почесать голову. Например, если нужно сначала настроить службу API, прежде чем конечная точка что-либо возвратит, а затем использовать одну конечную точку, чтобы получить определенный объект, который передается в параметры другой конечной точки, и т.д., функции Try-it-out в Swagger UI не будет иметь большого смысла для пользователей без подробного руководства.
• Запросы к реальным данным: Некоторые пользователи могут не осознавать, что нажатие кнопки Try-it-out создает реальные вызовы для их собственных учетных записей на основе используемых ими ключей API. Смешивание использования исследовательской изолированной программной среды, такой ​​как Swagger, с реальными данными может впоследствии создать головные боли, когда пользователи начнут спрашивать, как можно удалить все тестовые данные или почему их фактические данные теперь испорчены. Для этих сценариев лучше всего настроить песочницу или тестовую учетную запись для пользователей. Но это легче сказать, чем сделать.
  Можно обнаружить, что компания не предоставляет «песочницу» для тестирования API. Все вызовы API выполняются только для реальных данных.
• Ограничения CORS: Можно столкнуться с ограничениями CORS (Cross-Origin Resource Sharing — обмен ресурсами между источниками) при выполнении вызовов API. Не все API принимают запросы, выполненные с веб-страницы. Если вызовы не выполняются, нужно открыть консоль JavaScript и проверить, не блокирует ли CORS запрос. Если это так, нужно попросить разработчиков внести коррективы, чтобы учесть запросы, инициированные из JavaScript на веб-страницах. См. CORS Support для более подробной информации.
• Проблематика обширных параметров тела запроса: конечные точки с длинными параметрами тела запроса, как правило, проблематичны. Один API может включать запросы с параметрами тела запроса длиной в сотни строк (тело запроса использовалось для настройки сервера API). С таким параметром тела запроса отображение пользовательского интерфейса Swagger оказалось непригодным для использования. Команда вернулась к гораздо более примитивным подходам (таким как таблицы) для перечисления всех параметров и их описания.

Некоторые утешения

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

Swagger UI обеспечивает определенно хорошую визуальную форму для API. Можно легко увидеть все конечные точки и их параметры (например, краткий справочник). Основываясь на этой структуре, можно помочь пользователям понять основы вашего API.

Кроме того, изучение спецификации OpenAPI и описание своего API с его объектами и свойствами поможет расширить свой собственный словарь API. Например, станет понятно, что существует четыре основных типа параметров: параметры «пути», параметры «заголовка», параметры «запроса» и параметры «тела запроса». Типы данных параметров в REST: «Boolean», «number», «integer» или «string». В ответах содержатся «objects», содержащие «strings» или «arrays».

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

OpenAPI может не подходить для каждого API, но если API имеет довольно простые параметры, без большого количества взаимозависимостей между конечными точками, и если нет проблем исследовать API с данными пользователя, OpenAPI и Swagger UI могут быть мощным дополнением к документации. Можно давать пользователям возможность опробовать запросы и ответы.

С таким интерактивным элементом документация становится больше, чем просто информация. С помощью OpenAPI и Swagger UI мы создаем пространство для пользователей, которые одновременно могут читать нашу документацию и экспериментировать с нашим API. Эта комбинация имеет тенденцию предоставлять мощный опыт обучения для пользователей.

Ресурсы для дальнейшего чтения

Вот источники для получения дополнительной информации об OpenAPI и Swagger:

• API Transformer
• APIMATIC
• Carte
• Swagger editor
• Swagger Hub
• Swagger Petstore demo
• Swagger Tools
• Swagger UI tutorial
• OpenAPI specification tutorial
• Swagger2postman
• Swagger-ui Responsive theme
• Swagger-ui
• Undisturbed REST: A Guide to Designing the Perfect API, by Michael Stowe

🔙

Go next ➡

Специфицируй это. Доклад Яндекса / Хабр

Хорошая спецификация к API помогает клиентам его использовать. Несколько месяцев назад на большом Pytup разработчик Яндекса Александр Брязгин bryazginnn выступил с докладом о том, что собой представляет спецификация REST API на примере OpenAPI + Swagger и зачем нужна такая связка. Из конспекта можно узнать, как мы прикручивали автоматическую генерацию спецификации в уже готовом сервисе, какие библиотеки нам пригодились и какой есть тулинг вокруг спецификации OpenAPI.

— Всем привет, меня зовут Александр. Я хотел бы поговорить с вами про спецификации.

Если конкретно, я бы хотел затронуть несколько тем. Во-первых — что такое спецификации на примере спецификаций REST API. Далее — как мы в нашем сервисе прикручивали генерацию спецификации. И в конце, на сладенькое — какие есть инструменты, тулинг, чтобы использовать результаты нашей генерации спецификаций, на примере такой спецификации, как OpenAPI и Swagger UI.

Спецификация REST API

Что такое спецификации и что я под этим подразумеваю в своем докладе?

В первую очередь это Interface Description Language, язык описания интерфейсов, какое-то описание, которое соответствует определенному формату. Его можно парсить автоматически, потому что у него строгий формат и такая специфика, что оно не зависит от самого языка, на котором реализован интерфейс. То есть, допустим, у вас есть веб-сервер на Python, для Interface Description Language это не имеет значения.

Языков описания спецификаций достаточно много. Это спецификации для REST, RPC, GraphQL и т. д. Сегодня мы остановимся подробнее на спецификации REST.

OpenAPI

Давайте будем говорить о спецификациях на примере OpenAPI.

Сначала поймем, что такое OpenAPI. Это как раз таки language для описания спецификаций. Сам по себе он представляет собой файл — в формате YAML, JSON или XML, кому что больше нравится — с описанием интерфейса, ручек-endpoints и схем.

Swagger

Когда мы говорим про OpenAPI, нельзя не сказать про Swagger.

Swagger — это, по сути, UI для OpenAPI, который позволяет вам красиво визуализировать вашу спецификацию.

В Swagger, как и в OpenAPI, есть описание endpoints, которые есть в вашей спецификации.

Есть описание авторизации в вашем API.

Есть описание моделей или же схем, с которыми вы манипулируете в вашем API — допустим, принимаете на вход или отдаете на выход.

Есть описание примеров и ожидаемых запросов и ответов вашего API.

И дополнительно в своем Swagger, благодаря тому, что это UI и он запущен у вас в браузере, вы можете в реалтайме выполнять запросы к вашему API прямо здесь и сейчас.

^{_{Ссылка со слайда}}

С этим всем можно поиграться на тестовом стенде, подготовленном командой Swagger. Это petstore.swagger.io. Там есть пример спецификации, поднят Swagger. Вы можете сходить в реальный бэкенд и пощупать. Рекомендую.

Итак, мы говорим: OpenAPI, Swagger, спецификация. Но зачем все это нужно человеку, который пишет, допустим, бэкенд?

В первую очередь, спецификации часто используются на этапе проектирования нашего API. То есть нормальные люди, придя к задаче написания бэкенда, начинают с того, что описывают, что же они хотят реализовать. То есть они начинают проектировать свой API, список endpoints, которые они хотят реализовать, список схем, с которыми будут манипулировать, параметров и т. д. В этом случае спецификации и инструменты вокруг спецификаций очень удобны.

Помимо этого есть популярный кейс. Ради чего мы затаскивали спецификацию к нам в сервис? Это документирование. Наличие спецификаций дает вам такую хорошую возможность описывать ваш API и делиться этой информацией с кем-то: или с фронтендерами в вашей команде, или с внешними клиентами, которые хотят с вами интегрироваться.

Также благодаря тому, что спецификация написана в определенном строгом формате, ее можно автоматически процессить, то есть заниматься интроспекцией API. И поверх можно навертеть очень много инструментария, который позволяет облегчить вам жизнь. Конкретнее и подробнее расскажу чуть попозже.

Как мы готовим OpenAPI

Мы определились, зачем нам все это нужно. Давайте расскажу, как мы в нашем сервисе прикручивали генерацию спецификаций. Сначала немного контекста.

Когда мы пришли к мысли, что давайте запилим спецификацию, мы пошли не по нормальному пути, когда мы сначала написали проект, в смысле прототип со спецификацией. Мы уже подняли какой-то бэкенд, он у нас уже летел, и мы захотели расшарить спецификацию как способ документирования.

И наш бэкенд внезапно был на Python. В качестве фреймворка мы использовали Falcon, в качестве инструмента сериализации и десериализации данных — marshmallow, в качестве инструмента валидации — webargs.

На примере простейшей вырезки из petstore, о котором я говорил раньше, представим, как бы мог выглядеть наш сервис на этапе, когда мы захотели генерировать спецификацию.

В нашем сервисе упрощенно была бы пара схем: тип нашего домашнего животного, то есть категория, и, собственно, сами животные.

То есть мы бы описали несколько схем на Marshmallow. Дальше мы подготовили бы несколько ручек для того, чтобы, допустим, регистрировать и получать наших любимчиков.

И, собственно, описали бы сам application, которым подняли бы endpoint по созданию и получению pets.

Вот так это выглядело бы вместе. Достаточно простой сервис.

Давайте подумаем, какие у нас есть варианты формирования OpenAPI-конфига. Самый простой и наивный вариант, как я говорил ранее, — это просто файлик. Почему бы нам этот файлик не составить руками? Мы знаем, какие у нас есть данные на входе, у нас есть endpoints. Кажется очевидным, просто берем и пишем.

Но, во-первых, мы программисты. Мы не любим ничего делать руками. Мы хотим, чтобы нечто стандартное генерировалось за нас. Во-вторых, если бы мы поддерживали все руками, нам непременно бы пришлось поддерживать изменения API, а также файлик, который лежит где-то в другом месте. Как и любой сервис, наш продукт изменчив, и спецификация тоже.

Поэтому мы пришли к тому, что хотим генерировать OpenAPI-конфиг. С учетом нашего стека технологий мы нашли такую библиотеку, как apispec. Apispec — библиотека от производителей, то есть авторов Marshmallow и Webargs. Они вместе составляют большую экосистему.

Давайте посмотрим, как можно воспользоваться apispec на нашем стеке, чтобы научить его генерировать для нас спецификацию.

У нас был ресурс и определенный хендлер на метод get этого ресурса. У него есть какое-то тело.

Чтобы научить apispec, дать ему понять, что же мы делаем в нашей ручке, мы что-то дописываем в docstring. Мы дописываем туда описание, понятное человеку. В нашем случае это пример ответов: иногда бывает, наша ручка отвечает двухсоткой, и в теле нашего ответа есть JSON со схемой, моделью данных Pet.

На примере post-запроса мы описываем: помимо того, что есть ответ 201, в котором мы возвращаем Pet, есть еще ожидаемое тело запроса, который к нам приходит. И внутри этого запроса мы ожидаем JSON, и ожидаем, что этот JSON будет в формате Pet.

Мы добавили docstrings, дальше нам нужно научиться генерить спецификацию. Для этого мы пишем какой-то скриптик, красную кнопочку, и учим apispec генерировать для нас спецификацию. Мы декларируем объект apispec, у которого описываем какие-то метаданные нашего сервиса, и дальше просто пишем файл, сгенерированную спецификацию в формате YAML.

Давайте посмотрим, что для нашего огромного приложения сгенерировалось в этом файлике.

В первую очередь в этом файлике будет описание версии, в котором сгенерировалась спецификация. Это важно для того, чтобы все, кто будут интерпретировать эту спецификацию, понимали, в каком формате надо интерпретировать. От версии к версии спецификации меняются.

Дальше есть описание нашего сервиса. Это title, версия, возможно, будет какой-то description, если вы этого хотите, и дальше список серверов, на которые можно сходить, подергать ручки, увидеть и пощупать наш бэкенд.

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

Помимо схем туда прорастает описание самих endpoints. В данном случае прорастает описание по каждому методу.

По методу get у нас прорастает описание того, что мы делаем на метод get.

И на post проросло ровно то описание, которое мы положили в docstrings соответствующего endpoint. То есть мы уже получили какой-то файл.

Что нам теперь с ним делать? В чем польза? В первую очередь вы как владельцы бэкенда уже можете всем потенциальным клиентам, которые будут ходить в ваши ручки, отдавать эту спецификацию. И это поможет ребятам проинтегрироваться. То есть тот файлик, который мы сгенерировали, не заставляет вам выколоть глаза. Он достаточно читабельный. Его можно посмотреть глазами и как-то распарсить.

Но это тоже сложно. Давайте посмотрим, какие есть другие инструменты, чтобы упростить себе жизнь и какой есть тулинг вокруг сгенерированной спецификации.

Плюшки

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

^{_{Ссылка со слайда}}

Первый инструмент, про который я хотел бы сказать, это Swagger-UI. Здесь и далее я буду приводить ссылочки или на веб-ресурс, в котором можно потыкать соответствующий инструмент, в данном случае это SwaggerHub, или на команду запуска соответствующего документа с помощью Docker.

Мы все очень любим Docker. Docker помогает вам не ставить на локале JavaScript или какую-нибудь Java. Просто берете, запускаете одной командой, и у вас все работает.

Так вот, Swagger-UI — это, по сути, утилита, которая позволяет вам красиво отобразить вашу спецификацию. Как я ранее говорил, это запущенные на локале с помощью Docker, возможно, Swagger.

Вы можете на локале посмотреть или расшарить, запустив на своем железе, спецификацию в Swagger. И дальше отправлять всех ваших потенциальных пользователей на эту спецификацию. Она уже намного более понятная, красивая. Прямо в ней можно делать выполнение запросов.

^{_{Ссылка со слайда}}

Помимо Swagger-UI есть удобный инструмент Swagger-editor. Можно использовать его в вебе, можно поднять на локале или на любой машинке. Он позволяет вам в реалтайме изменять спецификацию и видеть ее отображение прямо тут. То есть это очень удобный инструмент на этапе, допустим, проектирования API, когда у вас не генерируется спецификация, а вы хотите как-то подшаманить или описать ваш бэкенд, не имея ни реального, ни генерируемого бэкенда позади,.

Дальше есть замечательный инструмент Prism. На нем я бы хотел остановиться поподробнее. Prism — это утилита от Spotlight. Он позволяет вам, имея спецификацию, поднять mock-server, который будет работать согласно той спецификации, которую вы ему скормили.

То есть в данном случае мы видим запуск Prism поверх спецификации, которую я стащил как раз из-под сваггеровского store. Мы видим, что Prism нашел все endpoints, которые указаны в спецификации, и сказал, что честно их замокал.

Давайте попробуем пощупать, что Prism умеет делать.

В первую очередь, мы находим ручку, пробуем ее дернуть и внезапно видим, что Prism говорит нам: sorry, 401 ошибка. Мы идем в спецификацию и видим, что на самом деле эта ручка спрятана за авторизацией. Там явно описана секция секьюрити. В ней мы видим, что способ авторизации — OAuth, и понимаем: на самом деле Prism ожидал от нас какие-то авторизационные данные.

Давайте попробуем ему передать авторизационные данные согласно тому формату, который он ждет. Понятно, что токен здесь какой-то воздушный, для Prism неважно, какой он по сути. Ему важен именно формат. То есть, если он ждет именно OAuth, он ждет авторизационные данные в определенном формате.

Мы дергаем с Authorization и видим уже 400-ю ошибку. Смотрим, что же у нас в спецификации. В спецификации мы видим, что мы не передали некоторые обязательные атрибуты. Давайте их передадим.

Волшебный атрибут status. Он, на самом деле, дан согласно спецификации ENUM. Если бы мы передали статус, не входящий в этот ENUM, то получили бы четырехсоточку.

Здесь мы передали валидный статус и видим, что бэкенд ответил уже вполне валидным xml с данными. Данные в этом xml сейчас отдаются всего лишь сгенерированные из example, указанные в спецификации. То есть в спецификации для каждого поля есть такая секция, как example, где вы можете указать пример данных, которые могут вернуться. Здесь Prism просто вернул их.

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

Для этого случая мы декларируем определенный код, допустим, 400-й или 422-й, кому как угодно. То есть при валидном входе не всегда есть валидный выход. Поэтому в спецификации мы описываем различные варианты ответов. И мы можем явно при дергании ручки сказать Prism: в этот раз я жду, что ты мне ответишь, допустим, 404-й ошибкой. Допустим, это кейс, когда я дергаю ручку с айдишником, но такого айдишника нет.

Если подытожить, то какие в целом есть фичи, помимо тех, о которых я уже сказал? Опять же, это mock server, который вы можете поднять. Он будет отвечать согласно спецификации, валидировать запросы на авторизацию. Также он будет валидировать на те данные, которые вы ему отправили.

Помимо валидации запроса, он будет генерировать ответы. В простейшем случае, как я сказал, он генерирует ответы по example. Есть второй вариант — когда вы просите его явно: генерируй, пожалуйста, динамические ответы. Динамическая стратегия означает, что он, в зависимости от типа, допустим, int, будет генерировать какие-нибудь тысячи, миллиарды или еще что-нибудь. Или для строки странный и непонятный хэш.

Также, когда я рассказал на первом прогоне, что можно генерировать данные, мы задались вопросом: было бы прикольно, если бы Prism интегрировался c faker. Те, кто пользовался питоновским faker, наверное, знают, насколько он клевый, когда вы хотите замокать какие-то данные или эмулировать данные в базе.

Так вот, Prism написан на JavaScript. В JavaScript тоже есть Faker.js, и у Prism есть автоматическая интеграция с faker. Вы можете в своей спецификации явно указать типы faker-данных, которые ваша ручка будет отдавать. То есть OpenAPI поддерживает систему плагинов, которая позволяет расширять вашу спецификацию так, что OpenAPI и самому парсеру это не важно. Но если есть плагины, которые парсят вашу спецификацию, они могут пользоваться какими-то дополнительными полями.

Так вот, Prism предлагает вам использовать дополнительное плагин-поле X-faker. Очень удобно.

Здесь под звездочкой я указал, что в OpenAPI можно описывать callbacks. Это схема взаимодействия, когда вы регистрируете callback на определенную ручку и ждете, что после этого вам придет определенный callback на зарегистрированный вами url. Так вот, Prism и это умеет мокать.

Из интересного: Prism можно поднять не только в режиме mock, но и в режиме Proxy. Вы просто ставите эту Proxy перед своим реальным бэкендом, и все запросы, которые идут через Prism и возвращаются обратно, Prism будет валидировать на соответствие спецификации.

Если какие-то данные — допустим, вход или выход, request или response — будут расходиться, он будет писать это в логе. Он делает это достаточно прозрачно, это никак на реальном поведении не сказывается. И вообще, в документации написано, что это можно спокойно поднимать в продакшене. Честно говоря, сам не пробовал. Наверняка существует какой-то overhead, но про него пока сказать не могу. Вы можете пощупать, попробовать и рассказать.

Дальше можно через то, что я уже сказал, форсировать определенные запросы. То есть к mock server прийти и сказать: я хочу определенный example или тип ответа. Про тип ответа мы уже поговорили. Также в OpenAPI-спецификации есть возможность указать несколько вариантов ответов и их явно именовать.

Так вот, можно прийти и сказать Prism: в этот раз я хочу определенный example, в следующий раз я хочу другой example.

^{_{Ссылка со слайда}}

Про Prism поговорили. Теперь про Postman. Я его очень люблю. Так вот, у Postman есть из коробки интеграция с OpenAPI. Вы можете буквально двумя нажатиями кнопочек заимпортировать OpenAPI-спецификацию. И он создаст коллекцию запросов по вашей спецификации.

При этом он заранее предподготовит все query параметры, все body-параметры, весь environment и авторизацию. Вам останется только добить данные какими-то реальными айдишниками или еще чем-то, авторизационными токенами. Очень удобно.

Переходим от Postman дальше. Мы поговорили про Prism, у него есть функциональность — валидация запросов. На самом деле, есть отдельная утилита, которая позволяет вам нещадно поддосить ваш реально запущенный бэкенд и проверить, реально ли он работает согласно спецификации.

Dredd парсит спецификацию. Берет, дергает все ручки и смотрит, что же ему вернулось. В целом, к dredd можно относиться как к инфраструктуре по написанию тестов, потому что все его запросы можно дополнить своими хуками. То есть из коробки можно запустить dredd просто as is, как я запустил его вот здесь.

А можно запустить dredd, передав ему набор хуков, которые, на самом деле, работают в идеологии обычного теста. Там есть что-то, что поднимается на все множество тестов, есть хуки, которые запускаются перед тестом, после теста, вся инфраструктура.

^{_{Ссылка со слайда}}

Дальше хочу поподробнее поговорить про такой инструмент от самого Swagger, как Swagger-codegen. На самом деле это немного напоминает швейцарский нож. Начну с того, какие мысли были у ребят, когда они писали этот инструмент.

Обычно, когда кому-то нужно проинтегрироваться с бэкендом, вы в бизнес-логике редко описываете прямо здесь, на определенном этапе, http-запрос. Чаще всего вы инкапсулируете работу с определенным бэкендом в какой-то сущности, в клиенте.

Так вот, ребята пришли к мысли, что, имея спецификацию, мы достаточно понятно можем описать и предсказать, как выглядел бы клиент к этому бэкенду. И ребята сделали генератор клиентов.

Давайте попробуем запустить генерацию клиента по спецификации petstore. Мы увидим, что этот генератор сгенерировал сам Swagger-клиент, в котором есть сам Python-клиент. Тут в строке запуска можно явно увидеть, что я генерирую клиент на Python. На самом деле он поддерживает огромное количество языков. Что тут есть из важного? Фронтендерам понравится, что есть JavaScript, хипстерам понравится, что есть Go. Все, что вы хотите.

Так вот, помимо клиента на Python, он сгенерировал парочку волшебных папочек docs и test. О них мы потом поговорим чуть подробнее. И очень много сахара, чтобы вы могли обернуть этот клиент в уже готовую библиотеку. Тут есть gitignore, тут есть CI-файлики, допустим, для Travis, есть сахар для git. Есть requirements, setup.py и tox.ini. То есть все то, что поможет вам просто взять, закоммитить и отправить этот клиент уже в виде библиотеки, которую можно переиспользовать.

Давайте подробнее посмотрим, что же он нагенерировал в клиенте.

В клиенте он сгенерировал, помимо каких-то вспомогательных файликов, две очень важные директории api и models. В models у нас лежат те модели данных, которыми мы манипулируем. Каждая модель из себя представляет просто питоновский класс, который унаследован от object с __init__, который принимает всевозможные параметры этой схемы, и геттерами и сеттерами, которые меняют состояние объекта.

Помимо модели там также появились такие сущности, как PetApi — это как раз клиентские обертки над группой endpoints, которые OpenAPI группирует или по тегам, или по endpoints.

И в этом клиенте есть все ручки, которые вы можете подергать, передав реальные данные. Тогда они улетят на какой-то бэкенд.

Что в этом из сгенерированного клиента реализовано? Из интересного — контрактный подход. Давайте поподробнее про него расскажу.

Контрактный подход к программированию говорит о том, что когда вы реализуете взаимодействие между клиентом и сервером, вы на самом деле всегда закладываетесь на определенные правила, на контракты, будь то данные, которые клиент отдает серверу, или данные, которые сервер отдает клиенту.

Так вот, контрактный подход рекомендует вам каждый раз в реалтайме проверять ваши данные и ваше взаимодействие на соответствие контракту. Если этот контракт представляет собой схему данных, которые мы передаем, и не соответствует нашим ожиданиям, не удовлетворен, то нужно об этом сказать, показать ошибку прямо здесь и сейчас. Не ходить в реальный бэкенд, не ждать какую-нибудь четырехсоточку, а прямо сейчас сказать.

Или другой случай: мы сходили в бэкенд, получили какие-то данные, но они не соответствуют тому, что мы ждали. Допустим, какие-то поля, которые мы ожидали видеть заполненными, пришли пустыми. Мы скажем об этом здесь и сейчас, а не когда по стеку вызовов уйдем куда-то в лес и не узнаем, почему у нас что-то отвалилось.

Так вот, Swagger-codegen генерирует клиенты и модели согласно контрактному подходу. Он позволяет в реалтайме сказать: да, я хочу, чтобы клиент в режиме выполнения проверял все данные на соответствие контрактам. И если контракт не удовлетворен, он тут же об этом скажет.

Мы сгенерировали какой-то питонячий клиент с контрактным подходом, но помимо этого Swagger-codegen сгенерировал для нас stubs документации. На самом деле они достаточно простые, но их все можно докручивать по каждой модели.

Еще Swagger-codegen сгенерировал какие-то stubs тестов. Все для того, чтобы вы могли минимальными усилиями докрутить сгенерированный код и запустить его с тестами, с Continuous Integration, в виде библиотеки с гитом, со всеми прибамбасами.

Пройдемся еще раз вкратце. Мы посмотрели всего лишь один кейс — способ генерации клиентов к API. Из важного } контрактный подход. Очень хочется сказать: когда я сгенерировал клиента к реальному petstore по их спецификации и реально ходил в их бэкенд, то внезапно этот контрактный подход отловил невалидные данные, которые возвращал сам petstore.

Я сначала подумал — они немного странные. Сами сгенерировали спецификацию, а бэкенд у них работает неправильно. Но мне кажется, они сделали это специально, чтобы мы увидели мощь контрактного подхода. Данных было не так много, и они явно были сгенерированы.

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

Также можно конфигурировать таких клиентов и писать импорт своих моделей, а не тех, которые сгенерировал Swagger-codegen.

Помимо генерации клиентов к API, можно скормить генератору спецификацию и сгенерировать stubs самого сервера. Это очень странно. То есть вы генерируете какой-то бэкенд, который якобы работает согласно спецификации. Понятно, что там никакой бизнес-логики нет. Но возможно, это будет удобно в качестве какого-то scaffolding, то есть подготовки черновика, с которым уже можно что-то делать. Я не использовал, но рекомендую глянуть — возможно, вы найдете для себя что-то полезное.

Помимо всего прочего, он позволяет вам генерировать документацию в формате HTML и Confluence, если кто-то пользуется. Примеры, которые я хотел показать для OpenAPI, тоже на этом закончились.

^{_{Все перечисленные инструменты доступны по двум ссылкам внизу на слайде: openapi. tools и github.com/APIs-guru/awesome-openapi3}}

Хочу показать группы тулинга вокруг OpenAPI-спецификации. На самом деле инструментов очень много. Это просто группы, то есть типы инструментария, который вы можете использовать.

Из важного здесь есть конвертор из одной спецификации в другую. То есть вы можете из OpenAPI-спецификации генерировать API Blueprint или то, что вы любите, и наоборот. Есть библиотека для mock, для документирования. То есть все, о чем я рассказал, будет отражено в этих группах.

Есть ссылочка, по которой вы тоже можете пройти. Обязательно походите, посмотрите.

^{_{Ссылка со слайда}}

Помимо инструментов вокруг OpenAPI, есть инструментарий вокруг Swagger. Есть SwaggerHub и Swagger Inspector. Они выделены синеньким, потому что это веб-инструментарий. Вы можете прямо перейти туда и as a service воспользоваться SwaggerHub и Swagger Inspector, которые на самом деле являются суперпозицией следующих библиотек: Swagger-editor, Swagger-codegen, Swagger-UI. Все то, что мы только что обсудили.

Все библиотеки желтые, они в опенсорсе, как мы видели. Есть на GitHub, есть в виде Docker. Используйте.

Заключение

Что мы сегодня обсудили? Спецификацию REST API на примере OpenAPI и Swagger. Я хочу акцентировать внимание, что OpenAPI — всего лишь один из способов описания спецификации. Их много. Из интересных посмотрите еще API Blueprint. Возможно, кому-то еще что-то приглянется.

Также мы посмотрели Swagger. По сути это, как мы уже говорили, всего лишь красивый UI вокруг спецификации, который позволяет вам глянуть и поисследовать ее в удобном виде. На самом деле этих инструментов тоже много, начиная от популярного ReDoc и Sphinx, а заканчивая, по сути, Markdown. То есть вы можете из OpenAPI генерировать Markdown, и он будет красиво отображаться во всех GitHub, GitLab — везде, где захотите.

Также мы посмотрели пример на нашем стеке технологий, как мы сейчас генерируем спецификацию. Но как вы заметили, это достаточно сложно и неудобно, потому что мы, по сути, дублируем бизнес-логику и docstrings.


^{_{Ссылки со слайда: FastAPI, SAFRS, rororo}}

Из интересного я советую глянуть на FastAPI. Про это подробнее вам сегодня расскажет Стёпа. FastAPI помогает вам генерировать спецификацию из коробки. Вы там можете вообще ни о чем не задумываться. Просто пишете код и получаете готовую спецификацию.

Есть еще два фреймворка: SAFRS и rororo. Названия, конечно, волшебные. Они работают немного по другой модели, не заставляют вас не задумываться о спецификации и получать ее просто как побочный эффект. Наоборот, у вас есть спецификация, которая рулит хендлерами. Это, грубо говоря, specification driven development. У них не так много звездочек, как у FastAPI, но мне кажется, они заслуживают внимания, гляньте обязательно.

И напоследок мы обсудили, какие вообще есть полезности вокруг спецификации на примере OpenAPI и Swagger. По всем пунктам я выношу ссылочки, посмотрите обязательно, там очень много интересного:

— OpenAPI / Swagger
swagger. io/docs/specification/about

— Пример на falcon + marshmallow + apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

— Плюшки OpenAPI / Swagger
openapi.tools
swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

Какой у меня вообще был посыл доклада? Ребята, писать спецификации — это не какая-то бюрократия. И это не так сложно, как может показаться на первый взгляд, а достаточно просто и дает много полезных инструментариев, открывает вам большие возможности.

Пишите спецификации. Рекомендую. Спасибо большое.

---

Весь код и ссылки доступны в презентации.

Что такое спецификация Open API?

Поскольку мир разработки веб-API значительно расширился в последние годы, программистам стало необходимо разрабатывать интуитивно понятные средства, с помощью которых машины и люди могут беспрепятственно взаимодействовать. Следовательно, переход к сервисным приложениям и микросервисам сделал необходимым для разработчиков наличие стандартного формата для определения структуры и синтаксиса restful API. Именно здесь на помощь приходит спецификация Open API. Она позволяет упростить процесс разработки приложений, предлагая уникальный машиночитаемый интерфейс, когда задействованы несколько интерфейсов, протоколов и сред.

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

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

Содержание

• 1 Что такое OpenAPI?
• 2 Для чего используется OpenAPI?
  • 2.1 1. Генерация кодов
  • 2.2 2. Генерация документации по API
  • 2.3 3. Тестирование API
  • 2.4 4. Лучшее сотрудничество при разработке API
• 3 В чем разница между API Swagger и Openifference?
• 4 Как создать спецификацию OpenAPI swagger?
• 5 Как преобразовать коллекцию Postman в OpenAPI с помощью APITransform

Что такое OpenAPI?

Open API — это инициатива или формат для создания и разработки стандартного и независимого от языка машиночитаемого интерфейса, который может определять, использовать, визуализировать и создавать REST API и веб-службы. Это формат с открытым исходным кодом, который упрощает разработку приложений, позволяя создавать машиночитаемые описания API. Открытые API позволяют разработчикам описывать и определять все основные элементы API, в том числе:

• Имеющиеся конечные точки и назначение каждой конечной точки
• Входные и выходные параметры для каждой операции
• Методы аутентификации
Учетные данные API
• , такие как лицензия, контактная информация, условия использования и другие важные сведения.

Как правило, спецификации OpenAPI записываются в форматах JSON и YAML, которые легко понимают машины и люди. OpenAPI предлагает стандартный формат для взаимодействия и понимания RESTful API с минимальной логической реализацией. Это позволяет как компьютерам, так и людям обнаруживать и понимать возможности API без необходимости доступа к исходному коду, чтения дополнительной документации или проверки сетевого трафика.

Для чего используется OpenAPI?

OpenAPI можно использовать для различных целей в экосистеме API. К ним относятся:

1. Генерация кодов

OpenAPI позволяет генерировать коды с использованием нескольких языков, которые поддерживаются генераторами кода. С помощью OpenAPI вы можете разрабатывать серверные заглушки, используя выбранный вами язык.

2. Создание документации API

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

3. Тестирование API

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

4. Улучшение сотрудничества при разработке API

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

В чем разница между Swagger и Open API?

Хотя вы, возможно, сталкивались с тем, что термины swagger и OpenAPI используются как синонимы на форумах по разработке API, это не означает, что это одно и то же. Как было определено ранее, OpenAPI — это стандартный и независимый от языка интерфейс, используемый для создания, использования, определения и визуализации Rest API. Спецификация является детищем инициативы OpenAPI, известной организации, состоящей из всемирно известных компаний, таких как Swagger, Google, Microsoft и IBM.

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

OpenAPI ранее был известен как Спецификация Swagger, потому что инструменты Swagger существовали вместе с ним в течение очень долгого времени. Однако, поскольку OpenAPI широко используется в отрасли, его по-прежнему можно поддерживать другими инструментами, помимо тех, которые работают на Swagger.

Как создать спецификацию OpenAPI swagger?

Разработчики и программисты могут создавать или генерировать спецификацию OpenAPI swagger с помощью интуитивно понятного Swagger Inspector, выполнив следующие действия:

1. Войдите в свою учетную запись Swagger Inspector.
2. Позвоните в свой API
3. Выберите нужные запросы на панели истории и создайте определение API.
4. Следуйте инструкциям, которые будут отображаться, пока не дойдете до SwaggerHub.
5. Дайте вашему API имя.
6. Теперь ваше определение полностью создано.

Как преобразовать коллекцию Postman в OpenAPI с помощью APITransform

При работе с Postman иногда может потребоваться преобразовать коллекцию Postman в OpenAPI для более удобного использования. APITransform — это бесплатный онлайн-ресурс, который позволяет программистам и разработчикам преобразовывать коллекции postman в спецификации OpenAPI за несколько шагов. Вот как это сделать:

1. Найдите https://apitransform. com и нажмите кнопку «Загрузить коллекцию почтальона» на панели инструментов.
2. Заполните необходимые учетные данные, прежде чем начать преобразование ваших коллекций Postman. Здесь вам нужно будет указать свое имя и фамилию, адрес электронной почты, название вашей компании.
3. Загрузите файл коллекции почтальонов и конвертируйте его.
4. Загрузите преобразованный файл по ссылке, которая появится через несколько минут
5. Теперь вы можете добавить свой API на рынок RapidAPI.

5/5 — (1 голос)

Стандартизированный жизненный цикл API на основе спецификаций

Домашняя страница InfoQ Статьи Стандартизированный жизненный цикл API на основе спецификаций

Архитектурный дизайн

Закладки

15 марта 2022 г. 15 мин читать

по

• Кин Лейн

проверено

• Стиф-Ян Виггерс

Напишите для InfoQ

Присоединяйтесь к сообществу экспертов. Увеличьте видимость.
Развивайте свою карьеру.Подробнее

Ключевые выводы

• Не существует единой спецификации API, которая управляла бы ими всеми, все они работают вместе.
Спецификации API
• — это больше, чем просто документация, являющаяся частью жизненного цикла.
• Разработка API в первую очередь — не единственный способ создать пригодную для использования спецификацию API.
Спецификации API
• необходимы для соблюдения нормативных требований.
• Команды лучше сотрудничают и лучше координируют свои действия, используя спецификации API.

На QCon Plus в ноябре прошлого года Кин Лейн, главный евангелист Postman и руководитель группы открытых технологий, представил спецификации API. Спецификации API важны для Lane и Postman. Поэтому он хотел немного рассказать о том, как, по их мнению, спецификации API влияют на то, как они производят и потребляют API.

Спецификации API не новы

Спецификации API не новы. Язык описания веб-служб (WSDL) определял веб-службы в течение последних 20 лет. Как только появился более веб-подход к API, мы также увидели развитие WADL, помогающего нам описать поверхностную область наших API. Но только когда в 2011 году вышел Swagger, наша документация стала намного более интерактивной и удобной. Помогая разработчикам понять, что делает API и как они могут его использовать, мы начали видеть преимущества спецификаций API.

К 2015 году Swagger вырос. Это было во второй версии. Он был помещен в Linux Foundation, создав инициативу OpenAPI для продвижения спецификации и переименовав ее в OpenAPI. Кроме того, помогая нам описывать наши HTTP API и веб-перехватчики за последние пять или шесть лет и предоставляя краеугольный камень того, как мы определяем, проектируем, доставляем, развертываем и устареваем наши API. Попутно AsyncAPI появился как родственная спецификация, позволяющая нам использовать тот же словарь, но для описания API, управляемых событиями и сообщениями, предоставляя формат, который мы можем использовать в нескольких протоколах.

OpenAPI

Давайте посмотрим только на OpenAPI. OpenAPI позволяет нам описать поверхность наших синхронных API — описать информацию, что делает API, где вы можете его найти, серверы. Что еще более важно, отдельные пути, параметры и детали каждого ответа, включая схемы, проанализированные как тело запроса или возвращенные как часть каждого ответа. OpenAPI предоставляет машиночитаемый способ JSON или YAML для описания того, что представляют собой наши API, что делают API HTTP/1.1, и позволяет разработчикам использовать эту спецификацию на разных этапах жизненного цикла API.

AsyncAPI

AsyncAPI позволяет нам описать поверхность наших асинхронных API, опираясь на то, что дал нам OpenAPI, и определяя каналы, сообщения и привязки. Например, API публикации и подписки через TCP, MQTT, AMQP позволяет нам определить, как эти API работают в нескольких протоколах, и описать, какие схемы используются как часть полезной нагрузки для публикации и подписки, какие сообщения отправляются туда и обратно в эти асинхронные API. . И OpenAPI, и AsyncAPI позволяют нам сегодня описать большинство API в нашем наборе инструментов.

Схема JSON

Схема JSON позволяет нам описывать и проверять полезные нагрузки этих API. Это дает нам машиночитаемый способ описания объектов, их свойств, типов данных, которые они содержат, а также того, что на самом деле требуется для проверки этих объектов. Схема JSON используется в нескольких OpenAPI, а также в AsyncAPI. У них есть свои собственные словари схемы JSON, которые позволяют им описывать и проверять полезную нагрузку запроса и ответа в случае OpenAPI. Они публикуют и подписываются на полезные нагрузки в контексте AsyncAPI. Опять же, предоставление машиночитаемого способа, который позволяет нам описать, что делают наши API — какие ресурсы анализируются туда и обратно, и какие возможности инкапсулированы в эти очень абстрактные API, которые часто трудно увидеть и проверить.

Спецификации API обеспечивают поддержку жизненного цикла API

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

Спецификации API также используются для создания фиктивных серверов. Эти фиктивные серверы могут быть частью подхода к разработке API. Во-первых, спроектируйте его и смоделируйте его, чтобы вы могли убедиться, что он делает то, что должен делать. Далее его можно использовать как часть контроля качества и тестирования. Затем некоторые группы используют его для песочниц в производственных средах, поэтому разработчикам не нужно играть с производственными данными, когда они изучают, что делает API.

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

Тот же подход можно использовать для обеспечения безопасности. Вы можете использовать свои спецификации OpenAPI или асинхронный режим для сканирования поверхности ваших API, поиска уязвимостей и аудита аутентификации. Затем проверьте наличие других распространенных уязвимостей, используя OWASP Top 10, пытаясь понять, настолько ли безопасны ваши API, насколько они должны быть согласованы между командами. Кроме того, еще одним распространенным способом поддержки жизненного цикла спецификаций API является генерация кода. Многие компании используют OpenAPI и AsyncAPI для создания клиентского или серверного кода, поэтому вы можете использовать спецификацию для создания кода, позволяющего развертывать API, развертывать его на шлюзе или создавать пакеты SDK на различных языках программирования.

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

Множество способов воплотить в жизнь вашу спецификацию API

Существует множество способов воплотить в жизнь вашу спецификацию API. Один из наиболее заметных и новейших подходов — дизайн в первую очередь. Вы начинаете с OpenAPI или AsyncAPI, создаете шаблон, а затем проектируете его вручную, гарантируя, что он точно делает то, что вам нужно. Затем создайте фиктивный сервер и опубликуйте документы, чтобы другие заинтересованные стороны и другие члены команды могли использовать его и давать отзывы об этом API, что позволит вам разработать API, смоделировать его и задокументировать до того, как вы на самом деле напишете код. После того, как вы достаточно итерируете его, вы можете опубликовать его как API.

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

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

Спецификации использования отраслевых стандартов

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

Open Referral — это еще один стандарт API, который использует OpenAPI для определения муниципальных, городских, окружных медицинских и социальных служб, что позволяет городам более эффективно обмениваться данными между штатами и странами. Другой — OpenTravel, определяющий то, как мы поставляем API в индустрии туризма, работая с авиакомпаниями, гостиничным бизнесом и другими вещами. Опять же, предоставление общего набора стандартов может использоваться для развертывания API для путешествий, что делает отрасль более функциональной.

Другой пример — Открытый геопространственный консорциум. Они работают над стандартами гео API, и вы можете найти спецификации OpenAPI для их API. Это всего лишь снимок. Есть много других стандартов, включая автомобильную промышленность и страхование. В большинстве отраслей, где API оказывают влияние, вы можете найти OpenAPI и все чаще AsyncAPI для определения этого ландшафта.

Спецификации обеспечивают основу для управления

При наличии OpenAPI, AsyncAPI и схемы JSON мы получаем основу для реализации управления в крупных корпоративных организациях. OpenAPI и AsyncAPI дают нам возможность устанавливать рекомендации по дизайну. Как должны быть описаны наши пути? Какие параметры? Должны ли они быть верблюжьими или змеиными? Как должна выглядеть схема? Как схемы развиваются, чтобы свести к минимуму критические изменения? Эти рекомендации по проектированию можно систематизировать и применять в машиночитаемом виде к OpenAPI и AsyncAPI. Правила линтинга. Очень часто используется линтинг OpenAPI или AsyncAPI, описывающий API, чтобы вы могли проверить, имеет ли он определенную структуру и форму. Вот что нам дает линтинг. Мы можем определить правила, которые составляют наши рекомендации по проектированию и общее управление предприятием. Мы можем применить эти правила к этим контрактам API, которые мы определили. Затем мы можем применить это с помощью контрактного тестирования, чтобы убедиться, что эти правила применяются во время проектирования, разработки и сборки.

Эти спецификации позволяют нам управлять изменениями. Эти объекты определяются схемами. Эти API-интерфейсы, определенные OpenAPI и AsyncAPI, обеспечивающие доступ к этим объектам, со временем будут меняться. OpenAPI, AsyncAPI и схема JSON позволяют нам количественно оценить это изменение. Примените к этому семантическое управление версиями на основе дат или другие типы и контролируйте, как эти ресурсы и возможности развиваются. Тогда мы можем автоматизировать все это. Мы можем автоматизировать его, поэтому он находится в инструментах проектирования, и получать обратную связь в режиме реального времени, когда дело доходит до редактирования схемы OpenAPI, Async или JSON. Вы можете применить во время конвейера или во время разработки в среде IDE или командной строке и позволить реализовать управление на протяжении всего жизненного цикла API и между группами разработчиков, помогая им автоматизировать применение управления. Затем попутно научитесь тому, что хорошее управление всегда включает в себя необходимые ресурсы. Каждая возможность управления становится возможностью узнать, почему это управление важно и как оно работает.

Спецификации API — это то, как мы работаем вместе как команда, поэтому вы видите это подтверждение в документации. Вот почему Swagger UI и Redoc, а также документация, основанная на спецификациях, стали настолько важными. Именно так мы, производители API, общаемся с потребителями API. По мере того, как они расширяются и применяются на протяжении всего жизненного цикла API, эти спецификации открывают возможности для совместной работы. Теперь мы можем делиться артефактами. Я могу поделиться тем, что я имею в виду, когда говорю о пагинации API. Это спецификация для него. Я могу поделиться тем, что я имею в виду, когда говорю, что это объект изображения. Я могу поделиться схемой JSON для этого. Совместное использование и сотрудничество вокруг этих артефактов позволяет нам работать ближе друг к другу и иметь одно и то же значение, кодифицированное в этих структурах. Затем, поскольку мы можем запечь это с нашим существующим контролем версий, у нас есть эти артефакты. Они могут жить вместе с кодом, который мы используем для развертывания, автоматизации, использования и работы с этими API.

Наши OpenAPI и AsyncAPI живут в рабочих областях, где они разрабатываются. Они находятся в репозиториях GitHub, GitLab и Bitbucket, где код фиксируется и используется во всей инфраструктуре для развертывания и автоматизации с помощью этих API. Все это позволяет нам стандартизировать команды, поэтому мы лучше общаемся, сотрудничаем, делимся информацией и располагаем этими артефактами, которые помогают нам понять, что имеется в виду, когда мы говорим об этих очень абстрактных концепциях API. Это помогает нам найти общий язык, стандартизировать то, как мы работаем, и автоматизировать это с помощью системы управления версиями. Это можно сделать на уровне команды, на уровне организации и с использованием стандартов на отраслевом уровне, что позволяет API быть более последовательным и итеративным на протяжении всего жизненного цикла.

Спецификации — это язык наших бизнес-операций

Эти OpenAPI, когда они становятся зрелыми, дают нам возможность определять различные области наших операций. Вот как мы разделяем различные направления бизнеса, другие области, которые мы используем для работы. Он может в значительной степени описать и определить, как устроены наши команды — как мы организуем наши команды и работаем в рамках этих различных направлений бизнеса и групп. OpenAPI, AsyncAPI и схема JSON с тегами для всех из них позволяют нам разделить все наши ресурсы и цифровые возможности в этих разных доменах, описывая другие ресурсы, которые у нас есть — различные изображения, видео, людей и адреса, все дополнительные цифровые ресурсы, которые у нас есть, а также возможности, алгоритмы и действия, предпринимаемые с этими ресурсами.

Описание всего этого в OpenAPI и пометка вещей помогают нам установить и формализовать наш словарь того, как мы это описываем. Мы используем эти схемы, которые публикуем в API как часть запросов, получаем обратно в виде ответов, публикуем, подписываемся в мире API, управляемом событиями. Мы стандартизируем то, как мы описываем эти объекты и как мы говорим о них. Мы сокращаем избыточность этих ресурсов и возможностей, создавая гораздо больше логических доменов для нашей работы. Убедитесь, что он максимально эффективен и четко определен. Тогда эксперты в предметной области могут действительно помочь направлять и управлять этой частью наших бизнес-операций.

Спецификации предназначены для людей и для машин

Спецификации предназначены для людей и для машин, даже несмотря на то, что они написаны в JSON или YAML и в значительной степени машиночитаемы и структурированы для импорта в различные службы и инструменты. Их можно использовать как часть системы контроля версий. Таким образом можно автоматизировать жизненный цикл API. Они очень нужны и людям. Крайне важно, чтобы мы использовали их, повторяли их, документировали и делали их доступными для людей для использования в их работе. Спецификации часто рассматриваются как инструмент разработчика. Они все чаще используются менеджерами проектов и инженерами, разработчиками API и архитекторами для формирования доменов в своих корпоративных организациях и используются как способ проверки проекта, проверки безопасности и другими способами. Использование его в качестве артефакта для обсуждения с разработчиками, которые создают API и приложения на их основе. Спецификации должны быть актуальными, потому что люди зависят от этого. Спецификации помогают нам решить множество человеческих проблем и противоречий, с которыми мы сталкиваемся в наших организациях. Важно поднять его, уменьшить масштаб и рассматривать спецификации как не просто документацию, не просто генерацию кода или просто артефакт JSON где-то на сервере. Это во многом контракт, который люди используют, чтобы продвигать свои операции и добиваться успеха.

Стандартизированный жизненный цикл API на основе спецификаций

Стандартизированный жизненный цикл API означает, что все эти ресурсы и возможности определены как машиночитаемые артефакты. Мы не просто фокусируемся на HTTP/1.1, REST или существующих способах развертывания API. У нас есть разнообразный набор артефактов, которые позволяют нам описывать управляемые событиями и сообщениями, GraphQL, gRPC, Kafka и NATS. Мы можем использовать полный набор API-решений, которые помогают нам описывать, определять, доставлять и использовать эти API таким образом, чтобы это было выгодно как производителю, так и потребителю. Это помогает нам стандартизировать то, как мы определяем и разрабатываем API — как мы поставляем, как мы делаем это в масштабе между командами и организациями. Когда вы идете в большую корпоративную группу и запускаете API, он имеет те же характеристики. Он имеет те же параметры свойств. Он имеет последовательную документацию. В нем есть библиотеки кода, которые мне нужны, и они используют соглашения, соответствующие языку программирования, который я использую.

Все это управляется этими спецификациями API. OpenAPI и AsyncAPI очень часто используются в качестве ограждений для этого. Они публикуются в центральном каталоге либо внутри организации, либо извне, с партнерами и сторонними потребителями. Эти OpenAPI, AsyncAPI и схему JSON можно использовать в любых службах или инструментах. Производитель API имеет гораздо более плавный, высокоскоростной, эффективный, гибкий и гибкий способ доставки API, реагирования на изменения и предоставления своих API. Потребители этих API имеют доступ к тем же контрактам, поэтому они знают, когда что-то меняется. Они могут автоматизировать, создавать и интегрировать эти API, не продираясь через документацию. Они могут просто импортировать OpenAPI. Они могут импортировать AsyncAPI. Они могут использовать схему JSON для проверки и тестирования. Затем они могут использовать все инструменты, созданные производителем API на основе этих спецификаций, и заставить их работать.

Стандартизированный жизненный цикл API, основанный на спецификациях, — это то, что вы видите в большинстве корпоративных организаций, которые потратили последнее десятилетие на общедоступные API или предыдущие пять или шесть лет активно инвестировали в микросервисы. Вы видите, как они работают над тем, чтобы научиться использовать OpenAPI в своей корпоративной организации. Во-первых, принятие и изучение того, как использовать AsyncAPI. Затем с помощью схемы JSON получить доступ к их внутренним данным, схеме и артефактам, которые анализируются. Приоритетом номер один для организаций, архитекторов и руководства некоторых из этих более прогрессивных компаний, ориентированных на будущее, является принятие этих спецификаций API, стандартизация вокруг них, а затем применение их в течение известного жизненного цикла API.

Резюме

Многие люди запутались в API и просто сосредотачиваются на документации, коде или дизайне и архитектуре этих OpenAPI. Надеюсь, это уменьшит масштаб и покажет, как OpenAPI, AsyncAPI и схема JSON работают вместе. Что еще более важно, как они применяются на протяжении согласованного жизненного цикла API. Потому что, как только вы сможете стандартизировать и стабилизировать его на протяжении всего жизненного цикла таким образом, именно здесь вы начнете видеть преимущества, когда речь идет о скорости работы, производительности, качестве и общем управлении происходящим. Я рекомендую перейти к OpenAPI, AsyncAPI или JSON Schema — всем трем решениям с открытым исходным кодом, которые позволяют вам описать, как вы будете использовать свои API. В каждом из этих сообществ вы можете многому научиться и поработать в рамках своей деятельности.

Об авторе

Кин Лейн

Показать ещеСкрыть

Оцените эту статью

Принятие

Автор связался с

Информационный бюллетень InfoQ

Обзор контента прошлой недели на InfoQ, который рассылается каждый вторник.