Ответ 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 и многое другое), он просто терпит неудачу в предоставлении решения обновленного вопроса, указанного выше.