Ответ 1

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

Swagger поддерживает только подмножество схемы JSON Draft 4

Спецификация состояний Swagger 1.2 и 2.0 поддерживает только подмножество JSON Schema Draft 4. Это означает, что:

• нельзя полагаться, что каждая действительная схема JSON может полностью поддерживаться Swagger.
• мышление XML, Swagger поддерживает только каноническое представление подмножества структур JSON, предоставленных проектом JSON Draft 4.

Другими словами:

• Swagger (1.2 и 2.0) не поддерживает использование многих структур JSON, которые действительны с точки зрения схемы JSON Draft 4 (то же самое относится к проекту 3).
• Swagger не поддерживает общие структуры данных XML, допускаются только очень ограниченные структуры.

На практике вы не можете начинать с разработки своих данных в JSON или XML, а Swagger вам нужно начинать и заканчивать Swagger.

Получение схемы JSON теоретически возможно, но нелегко

Я потратил некоторое время на кодирование библиотеки, которая взяла бы спецификацию API Swagger и создала проект JSON Schema Draft 4. Я отказался от двух причин:

• это было нелегко.
• получил разочарование в том, что я могу использовать только подмножество того, что предоставляет JSON Schema. У нас уже была какая-то полезная нагрузка JSON, и мне пришлось ее модифицировать, чтобы она соответствовала спецификации спецификации Swagger.

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

Если вам нужна полная поддержка JSON или XML Schema, используйте RAML

Изучая другие спецификации API, я нашел RAML. Поскольку он построен с нуля, поддерживая любые структуры данных JSON Schema Draft 3/4 или W3C XML Schema 1.0, опыт был отличным - с конструкцией моей полезной нагрузки я смог быстро разработать спецификацию API и после проверки реальных запросов и ответы против определенных схем были очень легкими, так как схемы являются важными компонентами спецификации без добавления каких-либо ограничений на них.

RAML был в версии 0.8 в то время (версия 1.0 еще не была выпущена).

Исправление вопроса приводит к реальному решению

Хороший вопрос составляет половину решения. Мой вопрос был неправильным, поскольку он пропустил выполнение моих реальных ожиданий. Исправленный вопрос:

Какую спецификационную структуру и технику использовать, чтобы указать REST API с использованием полезной нагрузки, определенной произвольной схемой JSON-схемы 4 или XML-схемой 1.0 W3C.

Мой ответ на такой вопрос:

• Создайте свою полезную нагрузку в схеме JSON Draft 4 или W3C XML Schema
• Опишите свой REST API с помощью RAML (v0.8 на данный момент).

Возможно, существуют и другие спецификации, но Swagger (ни v1.2, ни v2.0) определенно не тот. Помимо предоставления действительно большого количества функций (генерация кода, очень приятная документация по API и многое другое), он просто терпит неудачу в предоставлении решения обновленного вопроса, указанного выше.

Ответ 2

Только что открыл Swagger и спросил себя так же, как это было бы требованием.

Нашел этот ответ

Попробуйте прямо здесь:

http://petstore.swagger.wordnik.com/

и укажите это как ваш URL:

http://petstore.swagger.wordnik.com/api/api-docs/pet

Я вижу все модели. Ты не? Или я что-то упускаю?

здесь в своей группе пользователей: https://groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

заключается в том, что если "модели" ссылаются на действительную схему JSON 4.0/JSON hyper-schema

Ответ 3

Я только что написал инструмент pyswagger, который подойдет вам.

Он загружает декларацию API Swagger и способен преобразовать объект python в/из примитивов Swagger. Также предоставляйте набор клиентских реализаций (включая запросы и tornado.httpclient.AsyncHTTPClient), которые могут напрямую обращаться к службе с поддержкой Swagger.

Этот инструмент имеет тенденцию решать первую проблему, с которой я столкнулся при адаптации Swagger в python, и по-прежнему остается довольно новым. Добро пожаловать на любое предложение.

Ответ 4

У меня был некоторый успех, делая это так:

swagger.yaml → proto → jsonschema

Я использовал openapi2proto для создания прото файлов из Swagger yaml, затем protoc-gen-jsonschema, чтобы сгенерировать JSONSchemas. Это достаточно хорошо, чтобы получить типизированную JSONSchema, но proto3 не поддерживает "требуемые" типы, поэтому вы пропустите это.