Aprende en Comunidad
Avalados por :
Principales diferencias entre OpenAPI Spec 2.0 y 3.0: Guía de migración y compatibilidad
- Creado 01/03/2024
- Modificado 01/03/2024
- 22 Vistas
0
Cargando...
Hello Developers,
This post is to shed light on major differences between open api spec 2.0 and 3.0. Knowing the major non compatible differences will help migrating from 2.0 spec to 3.0 spec.
1. Version
How to know whether the api definition is adhering to 2.0 spec or 3.0 spec ?
In 2.0 spec there is a property called "swagger" which tells you the version of spec, for example
3.0
This is replaced with new property "openapi" and it should be used as below,
2. Multiple Servers
Open API spec 2.0 has placeholder only for one host or one server details and doesn't have support to have multiple server information. This drawback is taken care in 3.0 spec, so now there is new servers object array where you can have host information with any variable placeholders in the host url as well.
Example :
In the above example url has username, port and basepath as variable fields ( placeholders ), which are described in variables object section and also default values can be provided for each of them.
Rendering of this multiple server details in swagger ui is shown below,
3. Components
Open API spec 3.0 provides components object which can contain schemas, parameters, responses, examples, security schemes, links, request bodies, headers and callbacks. This component object won't affect the API untill it is referenced somewhere in the API.
Advantage : If multiple operations of an API needs similar input structure the the input structure can be defined under component as request bodies and can be reused in multiple paths. Similarly headers, responses and so on can be reused.
This post is to shed light on major differences between open api spec 2.0 and 3.0. Knowing the major non compatible differences will help migrating from 2.0 spec to 3.0 spec.
1. Version
How to know whether the api definition is adhering to 2.0 spec or 3.0 spec ?
In 2.0 spec there is a property called "swagger" which tells you the version of spec, for example
"swagger": "2.0"3.0
This is replaced with new property "openapi" and it should be used as below,
"openapi": "3.0.0"2. Multiple Servers
Open API spec 2.0 has placeholder only for one host or one server details and doesn't have support to have multiple server information. This drawback is taken care in 3.0 spec, so now there is new servers object array where you can have host information with any variable placeholders in the host url as well.
Example :
"servers": [
{
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]In the above example url has username, port and basepath as variable fields ( placeholders ), which are described in variables object section and also default values can be provided for each of them.
Rendering of this multiple server details in swagger ui is shown below,
3. Components
Open API spec 3.0 provides components object which can contain schemas, parameters, responses, examples, security schemes, links, request bodies, headers and callbacks. This component object won't affect the API untill it is referenced somewhere in the API.
Advantage : If multiple operations of an API needs similar input structure the the input structure can be defined under component as request bodies and can be reused in multiple paths. Similarly headers, responses and so on can be reused.
"components": {
"schemas": {
"Category": {
"type": "object",
"properties"
Pedro Pascal
Se unió el 07/03/2018
Facebook
Twitter
Pinterest
Telegram
Linkedin
Whatsapp
Sin respuestas
No hay respuestas para mostrar
Se el primero en responder
contacto@primeinstitute.com
(+51) 1641 9379
(+57) 1489 6964
© 2024 Copyright. Todos los derechos reservados.
Desarrollado por Prime Institute
Hola ¿Puedo ayudarte?