У мене є декларація API Swagger для служб, що використовують Swagger v 1.2

Моє первісне відчуття щодо Суаггера полягало в тому, що він дуже близький до схеми JSON (проект 3 і останнім часом проект 4), і буде відносно легко сформувати схему JSON для об'єктів запиту та відповіді.

Однак, хоча частина Swagger повторно використовує структури схеми JSON, виявилося, що вона використовує лише підмножину функцій, а також вводить власне успадкування в Models (using subTypesта discriminator).

Запитання: Чи існує якийсь проект чи фрагмент коду, який може генерувати корисну схему JSON із декларації API Swagger ?

Оптимально JSON Schema Draft 4 та використання Python (але я буду радий що-небудь знайти).

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

Swagger підтримує лише підмножину JSON Schema Draft 4

Специфікація станів Swagger 1.2 та 2.0, вона підтримує лише підмножину проекту JSON Schema Draft 4 (s. Тут ). Це означає що:

• не можна покладатися на те, що кожна діюча схема JSON може бути повністю підтримана Swagger.
• думаючи про XML, Swagger підтримує лише канонічне представлення підмножини структур JSON, передбачене проектом схеми JSON 4.

Іншими словами:

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

На практиці не можна починати з проектування даних у форматі JSON або XML, а у Swagger потрібно починати і закінчувати Swagger.

Отримати схему JSON теоретично можливо, але непросто

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

• це було зовсім не просто
• отримав розчарований висновок, що я можу використовувати лише підмножину того, що надає схема JSON. У нас вже було запропоновано деяку корисну навантаження JSON, і нам довелося почати її модифікувати, щоб відповідати тому, що дозволяє специфікація Swagger.

Окрім того, що я маю дуже приємний на вигляд інтерфейс для показу та тестування API (так, усі погоджуються, це візуально дуже приємно), мені здалося дивним, що структура специфікації не дозволяє нам використовувати те, що ми хочемо, але додає несподівані обмеження до нашого дизайну.

Якщо вам потрібна повна підтримка JSON або XML Schema, використовуйте RAML

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

RAML на той час був у версії 0.8 (версія 1.0 ще не виходила).

Виправлення питання призводить до реального вирішення

Хороше питання - це половина рішення. Моє запитання було помилковим, оскільки воно не відповідало моїм реальним очікуванням. Виправленим запитанням було б:

Яку структуру специфікацій та техніку використовувати, щоб вказати API REST із використанням корисного навантаження, визначеного довільним проектом схеми JSON 4 або схеми W3C XML 1.0.

Я відповів би на таке запитання:

1. Сконструюйте свою корисну навантаження в JSON Schema Draft 4 або W3C XML Schema
2. Опишіть свій REST API за допомогою RAML (v0.8 на даний момент).

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

Існує інструмент python, який робить те саме під назвою openapi2jsonschema . Ви можете просто встановити його за допомогою pip.

Readme для openapi2 показує найпростіший спосіб його використання:

openapi2jsonschema https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json

Сподіваюся, це допомагає.

Я щойно написав інструмент pyswagger, здається, відповідає вашим потребам.

Він завантажує декларацію API Swagger і може перетворити об'єкт python в / з примітивів Swagger . Також надайте набір реалізацій клієнта (включаючи запити & tornado.httpclient.AsyncHTTPClient ), які можуть безпосередньо надсилати запити до служби з підтримкою Swagger.

Цей інструмент, як правило, вирішує першу проблему, з якою я зіткнувся при адаптації Swagger в python, і досі є досить новим. Ласкаво просимо до будь-якої пропозиції.

Я мав певний успіх, роблячи це так:

swagger.yaml -> proto -> jsonschema

Я використовував openapi2proto для генерації прото файлів з Swagger yaml, а потім protoc-gen-jsonschema для генерації JSONSchemas з цього. Це досить добре, щоб отримати набраний JSONSchema, але proto3 не підтримує "необхідні" типи, тому ви пропустите це.