Swagger 2 y OpenAPI 3
Cambiar nombre
swagger: 2.0
openAPI:3.0.0
Estructura básica de URL de Swagger 2.0
OpenAPI 3.0 estructura de URL básica
Podemos definir una URL básica y cargar el valor de la variable a través de {} (similar a la plantilla de ruta. Cuando la usamos, el valor de la variable se puede definir a través del atributo de variable). , también se puede dar un valor predeterminado
Los conceptos definidos en Swagger 2 están estandarizados en OpenAPI 3 como componentes que se pueden reutilizar en múltiples lugares y se definen de la siguiente manera:
Swagger 2
p>
Uno de los aspectos más confusos de Swagger 2 es body /formData. Son un subconjunto de parámetros, solo puedes elegir uno de los dos, y si se usa el cuerpo, el formato será diferente de otros parámetros (solo se pueden usar parámetros del cuerpo, el nombre es irrelevante, el formato es diferente, etc. )
OpenAPI 3
Ahora el cuerpo se ha movido a una sección separada llamada requestBody y formData se ha fusionado en él. Además, se ha agregado cookie como tipo de parámetro (además del título, la ruta y las opciones de consulta existentes).
requestBody tiene muchas características nuevas. Ahora es posible proporcionar un ejemplo (o una serie de ejemplos) para requestBody. Esto es muy flexible (puede pasar un ejemplo completo, una cita o incluso un ejemplo de URL).
El nuevo requestBody admite diferentes tipos de medios (el contenido es una matriz de MIME_Types, como aplicación/json o texto/plain, aunque también puedes usar / para capturar todo el contenido).
Para los parámetros, tiene dos opciones para definir parámetros. Puede definir un "esquema" (como en el 2.0 original) para describir su proyecto a su gusto. Si desea ser más sofisticado, puede utilizar "contenido" en "requestBody".
Los comodines nos permiten definir respuestas como "4XX" sin tener que definir cada código de respuesta individualmente.
Las respuestas y los encabezados de respuesta pueden ser más complejos. Puede utilizar la carga útil de un objeto de "contenido" (como en la solicitud).
Los enlaces son una de las novedades más interesantes de OpenAPI 3. Es básicamente una forma de describir "lo que sigue".
Supongamos que obtiene un usuario con ID de dirección. El ID de dirección en sí es inútil. Puede utilizar el enlace para mostrar cómo "extender" y obtener la dirección completa.
En la respuesta "/users/{userId}" obtendremos un ID de dirección y este enlace explicará cómo obtener la dirección completa haciendo referencia a "$ respuesta .body#/addressId ".
Otro caso de uso es la paginación. Es muy flexible, lo que significa que puede manejar cualquier escenario de paginación limitado por el cursor.
Swagger 2
OpeanAPI 3
¡Una serie de cambios de seguridad! El "tipo base" ha cambiado de nombre a "/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.0".
master/versions/3.0.0.md#oasDocument
/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject