Пораженный Swagger, II

или: YAML, YAML, YAML

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

Существует стандарт, называемый спецификацией OpenAPI (OAS), описанный здесь (взято из репозитория github здесь). Эту спецификацию часто называют Swagger, из-за истории.

API

Онлайн-редактор Swagger имеет простой API-интерфейс Petstore, который можно загрузить через Файл → Открыть пример… →petstore_simple.yaml. Я сделал некоторые модификации, в основном:

В newPet добавлена ​​порода, ограниченная тремя перечисленными значениями («Ши-тцу», «Французский бульдог» и «Чау-чау»). Я также добавил диету:

diet:
    type: object
    properties:
      brand: 
        type: string
        enum: 
        - Purina Dog Chow
        - Purina Chow-Chow Chow
      scoops: 
        type: integer
      perDay: 
        type: integer

POST для создания нового питомца теперь состоит из двух полей:

          schema: 
            type: object
            required:
              - pet
            properties:
              pet: 
                $ref: '#/definitions/newPet'
              diet:
                $ref: '#/definitions/diet'

Я также добавил пользовательский формат petNameString в поле имени питомца (см. Типы данных в спецификации).

Редактирование в Swagger CLI

Существует интерфейс командной строки Swagger, который позволяет создавать проекты и редактировать документ API. Я создал проект Express под названием staggered, затем набрал:

> swagger project edit staggered

Это открыло документ API «Hello World App» (по умолчанию). К сожалению, я не могу импортировать YAML, поэтому я закрою редактор, скопирую свою версию Petstore YAML в папку проекта api/swagger как swagger.yaml, и перезапустите редактор. Никаких ошибок, никаких предупреждений, и ничего не кажется неправильным. Единственная проблема в том, что нет вариантов генерации кода — npm-модуль Swagger поддерживает простой проект со скелетной структурой папок, но не более того.

Редактирование на swagger.io

Я использовал редактор сайта swagger.io, чтобы внести свои изменения в документ YAML Petstore. Редактирование YAML напрямую может быть несколько утомительным. Редактор основан на Ace, а абстрактное синтаксическое дерево построено для проверки YAML по мере его ввода. Однако не всегда понятно, когда есть ошибки (а их будет много), что это за ошибка или на какой строке она находится.

При определении схемы диеты я накосячил. Там много Х. Где ошибка? Вы можете получить более подробную информацию об ошибке в панели пользовательского интерфейса редактора, но я редко находил ее полезной. Однако перезагрузка страницы, по крайней мере, немного сужает ситуацию:

Значит что-то не так с брендом. После небольшого поиска спецификаций и поиска определений в других местах документа я смог исправить синтаксис:

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

Апигей Студио

Теперь я могу зайти в Apigee Studio и использовать их онлайн-редактор. Я загружаю YAML в их редактор и никаких сюрпризов. Единственное заметное отличие, которое я вижу, это то, что Apigee Studio позволяет мне удалять части API в представлении пользовательского интерфейса, чего я не могу сделать в редакторе swagger.io. Есть и другие варианты генерации кода, о которых я расскажу в следующем посте.

чванливый редактор

Можно скачать swagger-editor from github и запустить его из командной строки. Обратите внимание, что это не то же самое, что запуск интерфейса командной строки Swagger.

git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start

Это дает редактор, работающий локально, который выглядит идентичным тому, что работает на http://editor.swagger.io/.

Рестлет Студия

Редактор Restlet Studio отличается от вышеперечисленных тем, что он основан на формах. Это значительно упрощает редактирование вашего API, а форма не допускает синтаксических ошибок. Это отличный инструмент для быстрой разработки нового API. Проблема в том, что он не полностью поддерживает весь OAS и будет вносить изменения в определения вашего документа API при его загрузке и экспорте. Вы даже можете потерять информацию, хотя большинство изменений в экспортированном YAML безобидны и в целом совместимы с swagger-editor; единственное исключение, с которым я столкнулся, заключается в том, что Restlet Studio разрешает поля описания в местах, которые распознает Swagger Editor, хотя это вызывает только предупреждения.

Информация, которую я видел, упала:

• пользовательские форматы
• теги
• встроенные определения объектов для параметров перемещены в записи $ref «anonymousRespresentation»

(По поводу последнего: я видел похожий рефакторинг определений в других редакторах, но не припомню подробностей вызывающих их определений API.)

Опять же, Restlet Studio — отличное место для начала написания API, но будьте осторожны при смешивании/сопоставлении его с другими инструментами Swagger. Я обменялся электронными письмами с несколькими людьми на restlet.com, и они признают, что удаление данных является проблемой, и планируют исправить ее в следующем выпуске.

Я уверен, что есть и другие редакторы на основе Swagger… если у вас есть любимый, напишите в комментариях!

Далее: swagger-codegen