example - Cómo generar el esquema JSON desde la declaración de Swagger API

swagger ui

Question

Tengo Swagger API Declaration para servicios usando Swagger v 1.2

Mi sentimiento original sobre Swagger fue que está muy cerca de JSON Schema (Borrador 3 y, más recientemente, Borrador 4) y será relativamente fácil generar el Esquema JSON para los objetos de solicitud y respuesta.

Sin embargo, aunque parte de Swagger reutiliza las estructuras del esquema JSON, resultó que usa solo un subconjunto de características, y también introduce su propia herencia en los modelos (utilizando subTypes y discriminator ).

Pregunta: ¿Existe algún proyecto o fragmento de código existente que pueda generar un esquema JSON utilizable a partir de la declaración API de Swagger ?

De manera óptima, JSON Schema Draft 4 y el uso de Python (pero estaré encantado de encontrar cualquier cosa).

Answer 1

Acabo de descubrir Swagger y me pregunté lo mismo que esto sería un requisito.

Encontré esta respuesta

Pruébelo directamente desde aquí:

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

y pon esto como tu url:

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

Veo todos los modelos. ¿Tú no? ¿O me estoy perdiendo algo?

aquí en su grupo de usuarios: https://groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

La pregunta es si "los modelos" se refiere a un hiper esquema de esquema JSON 4.0 / JSON válido

Answer 2

Acabo de escribir una herramienta que parece encajar con tu necesidad.

Carga la declaración Swagger API, y es capaz de convertir objetos Python a / desde primitivas Swagger . También proporcione un conjunto de implementaciones de clientes (incluidas las solicitudes & tornado.httpclient.AsyncHTTPClient ) que puedan solicitar directamente al servicio habilitado Swagger.

Esta herramienta tiende a resolver el primer problema que encontré al adaptar Swagger en python, y todavía es bastante nuevo. Bienvenido por cualquier sugerencia

Answer 3

Después de una pelea más prolongada con el uso de Swagger para especificar REST API y reutilizarlo en suites de pruebas relacionadas, compartiré mi propia experiencia con él (respondiendo mi propia pregunta).

Swagger solo admite el subconjunto de JSON Schema Draft 4

Especificación de Swagger 1.2 y 2.0 estados, es compatible solo con el subconjunto de JSON Schema Draft 4 (s. here ). Esto significa que:

• No se puede confiar en que cada Esquema JSON válido puede ser completamente compatible con Swagger.
• Al pensar en XML, Swagger solo admite la representación canónica del subconjunto de estructuras JSON proporcionadas por JSON Schema Draft 4.

En otras palabras:

• Swagger (1.2 y 2.0) no admite el uso de muchas estructuras JSON, que son válidas en términos de JSON Schema Draft 4 (lo mismo se aplica al Borrador 3).
• Swagger no admite estructuras de datos XML generales, solo se permiten estructuras muy restringidas.

En la práctica, no puede comenzar con el diseño de sus datos en JSON o XML, con Swagger tiene que comenzar y finalizar con Swagger.

Obtener el esquema JSON es teóricamente posible, pero no es fácil

Pasé algún tiempo codificando una biblioteca, que tomaría Swagger API Specification y crearía JSON Schema Draft 4. Me rendí por dos razones:

• No fue para nada fácil
• Me decepcionó encontrar que solo puedo usar un subconjunto de lo que proporciona el Esquema JSON. Ya teníamos una carga útil JSON propuesta y tuvimos que empezar a modificarla solo para adaptarnos a lo que permite el marco de especificación de Swagger.

Además de tener una interfaz de usuario realmente bonita para mostrar y probar la API (sí, todo el mundo está de acuerdo, es visualmente muy agradable), me ha parecido extraño que un marco de especificación no nos permita usar lo que queremos, pero agrega restricciones inesperadas a nuestro diseño

Si desea compatibilidad total con el esquema JSON o XML, use RAML

Investigando otros marcos de especificación API, encontré RAML. Como está construido desde cero al admitir cualquier estructura de datos JSON Schema Draft 3/4 o W3C XML Schema 1.0, la experiencia fue excelente: con la estructura de mi carga útil diseñada, pude crear la especificación API muy rápidamente y después de la validación de solicitudes reales y las respuestas contra los esquemas definidos fueron muy fáciles, ya que los esquemas son componentes esenciales de la especificación sin agregarles ninguna restricción.

RAML estaba en la versión 0.8 ese momento (la versión 1.0 aún no se había lanzado).

Corregir la pregunta conduce a una solución real

Una buena pregunta es la mitad de la solución. Mi pregunta era incorrecta ya que no cumplía con mis expectativas reales. La pregunta corregida sería:

Qué marco de especificación y qué técnica usar, para especificar la API REST usando la carga útil definida por el esquema arbitrario JSON Draft 4 o W3C XML Schema 1.0.

Mi respuesta a esa pregunta sería:

1. Diseña tu carga en JSON Schema Draft 4 o W3C XML Schema
2. Describe tu API REST mediante RAML (v0.8 en este momento).

Puede haber otros marcos de especificación utilizables, pero Swagger (ni v1.2 ni v2.0) definitivamente no es el caso. Además de proporcionar realmente muchas funciones (generación de código, documentación de la API muy atractiva y mucho más), simplemente falla al proporcionar una solución a la pregunta actualizada mencionada anteriormente.

Answer 4

Hay una herramienta de python para hacer lo mismo con el nombre de openapi2jsonschema . Simplemente puede instalarlo usando pip .

El archivo léame para openapi2 muestra la forma más sencilla de usarlo:

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

Espero que esto ayude.

Answer 5

He tenido cierto éxito al hacerlo así:

swagger.yaml -> proto -> jsonschema

openapi2proto para generar archivos proto de Swagger yaml, luego protoc-gen-jsonschema para generar los JSONSchemas a partir de eso. Es lo suficientemente bueno para obtener un JSONSchema mecanografiado, pero el protocolo no admite los tipos "requeridos", por lo que te pierdes esto.