Header Ads Widget

Ticker

6/recent/ticker-posts

Cómo escribir su primera especificación de OpenAPI

REST es la arquitectura indiscutible de referencia para la gran mayoría de las API actuales, lo que facilita un diseño simplificado y eficiente para desarrolladores de todas las aptitudes. Millones de API pueden atribuir su existencia a la popularidad de REST. Con tantas API inundando el mercado, el establecimiento de la estandarización puede mejorar la calidad general de la API y facilitar las integraciones.

Sabiendo esto, la industria de API se ha unido en torno a  Open API Specification (OAS) . La Especificación de OpenAPI describe cómo se deben desarrollar, entregar y hacer funcionar las API REST. El marco redefine la forma en que los desarrolladores abordan todo el ciclo de vida de la API. Si espera aprender los fundamentos detrás de OEA y por qué es útil, siga a continuación en nuestra guía de inicio.

Ventajas de la especificación OpenAPI

Especificación de OpenAPI

OpenAPI , el formato de definición de API estándar de la industria.

El desarrollo de la OEA está intrínsecamente basado en definiciones, lo que significa que la interfaz API tiene prioridad sobre todas las demás etapas del ciclo de vida. Esto significa crear solicitudes, respuestas y conjuntos de puntos finales. La especificación enfatiza el diseño sólido por encima de la lógica comercial, lo que en última instancia aumenta la facilidad de uso del producto final para el consumidor. Otras metodologías pueden obligarlo a hacer concesiones en esta área, luchar contra las limitaciones de tiempo y equilibrar las prioridades en competencia.

¿Cuáles son algunas otras ventajas clave de la especificación OpenAPI?

  • Legible por humanos y máquinas: fácil de entender sin acceso al código fuente
  • Agnosticismo lingüístico y compatibilidad con la mayoría de las pilas de tecnología
  • Código abierto y respaldado por la Fundación Linux
  • Desarrollo de primera definición, incluso tomado de sus API existentes
  • Diseño, documentación e implementación sincronizados, automáticamente
  • Inspiró a una animada comunidad de desarrolladores globales, respaldada por las principales plataformas API

Los creadores de OAS afirman que hace que el desarrollo de API sea intuitivo. Las herramientas brindan retroalimentación en tiempo real, habilitan el autocompletado y respaldan el trabajo individual o en equipo. La automatización, las pruebas y el monitoreo también se encuentran en el corazón de la experiencia del desarrollador de OEA. ¿Entonces, dónde empezamos?

Presentando Swagger

No hay mejor herramienta para diseñar API de OAS que Swagger, un sistema de herramientas creado desde cero para admitir OpenAPI . El ecosistema de Swagger fomenta la colaboración remota, pero da la bienvenida a la fiesta a los desarrolladores solitarios. Swagger en sí se divide en diferentes espacios de trabajo que impulsan cada etapa de desarrollo:

El editor Swagger

Los usuarios de un IDE o una aplicación de codificación como Visual Studio Code se sentirán como en casa dentro del Swagger Editor. Este espacio de trabajo es donde creará sus definiciones de API. También se podría notar que el panel de la derecha alberga sus estructuras - Visualización POSTGETy otras solicitudes de API OEA compatibles:

Adyacente se encuentra Swagger Petstore, un servidor de muestra que facilita la prueba de filtros de autorización y otros controles. Esto es posible a través de special-keyEl editor es un espacio de trabajo como cualquier otro; no dude en abrir proyectos recientes o iniciar un nuevo proyecto. El editmenú le permite convertir sus definiciones JSON en YAML. Una vez que tenga una arquitectura funcional, la interfaz del Editor le permitirá confirmar varios parámetros de diseño y luego ejecutarlos. Esta prueba integrada demuestra cómo podría funcionar su API de OAS, especialmente si se modifica continuamente.

Swagger Editor se basa en un navegador y admite la serialización JSON y YAML dentro de. Esto hace que sea más fácil interpretar los datos de su solicitud en un formato legible. Los lenguajes propietarios u oscuros complicarían este proceso. Las solicitudes se realizan en JSON, mientras que las respuestas están en JSON o XML. Dado que el editor está alojado en GitHub, también puede usarlo sin conexión.

Diseñar una solicitud PUT es simple dentro del Editor. Imagen cortesía de Swagger .

Diseñar una solicitud PUT es simple dentro del Editor. Imagen cortesía de Swagger.

Mientras escribe sus definiciones, el Editor analizará automáticamente su código en busca de errores, buscará oportunidades para autocompletar y resaltará la sintaxis de manera organizada.

A pesar de lo que le hemos mostrado en nuestro ejemplo (la API Swagger Petstore), un espacio de trabajo nuevo se ve como lo esperaría: un panel en blanco. Puede borrar cualquier texto de marcador de posición existente File -> Clear editorantes de comenzar a escribir. La construcción de una especificación requiere una configuración simple. Debe definir un título, una descripción y un número de versión para su API. También debe indicar qué versión de Swagger está utilizando en el typecampo:

Este será su punto de partida (de lo contrario, personalizado para su proyecto) cuando cree sus definiciones de API. Imagen cortesía de BlazeMeter .

Notará que estas entradas se mostrarán visualmente en el panel de la derecha. Esto le permite realizar un seguimiento de los cambios a medida que los realiza y evaluar sus impactos continuamente. El cuadro de alerta de error de Swagger iluminará las áreas de necesidad inmediata, evitando que los problemas entren en producción. El mismo panel también muestra los formatos y tipos de modelos en los que puede confiar en la fase de diseño, incluidos:

  • Order
  • Category
  • User
  • Tag
  • Pet
  • ApiResponse

Afortunadamente, el diseño visual de sus controles dentro del editor está ordenado y lógicamente codificado por colores. Es relativamente fácil seleccionar información crucial y la GUI es navegable. Sin embargo, hay más que menús desplegables y de acordeón. Puede editar directamente sus valores manualmente si es necesario realizar cambios. Este enfoque combina eficazmente la capacidad de configuración con la facilidad de uso. El diseño también se conoce como Swagger UI .

Swagger Codegen

Imagen cortesía de Swagger .

Codegen se centra en una cosa: optimizar el proceso de compilación mediante la generación de SDK y stubs de servidor. Esta creación de código automatizada funciona para cualquier API. Ya sea que esté monetizando su API o no, Codegen lo ayudará a llegar al mercado más rápido. Al crear una API, también es esencial comprender el alojamiento: ¿dónde se almacenarán sus datos y cómo puede diseñar un conducto adecuado a través del cual se puedan enrutar las solicitudes?

Codegen responde a estas preguntas "generando código de servidor estándar en más de 20 idiomas diferentes". La gente suele ver la configuración del servidor como una tarea tediosa y complicada que se deja solo a los expertos. Las herramientas de Codegen cierran la brecha de conocimiento al facilitar las cosas a los desarrolladores de todos los niveles. El proceso de Swagger en este sentido es low-code; afirman que solo se necesitan unos pocos clics.

Probablemente querrá que su API sea consumida por tantas personas como sea posible, especialmente si es pública . Los SDK son instrucciones para profesionales externos que impulsan la integración y mejoran la comprensión de su producto API. Swagger Codegen produce SDK en más de 40 idiomas.

La herramienta de servidor de Swagger es compatible con las API de OAS 2.0 y 3.0.

Entendiendo SwaggerHub

SwaggerHub se creó para equipos (y empresas) y promete una colaboración sencilla y una alineación de API con los objetivos comerciales. Las partes interesadas de varios grupos pueden inspeccionar, comentar y editar simultáneamente las API de OAS mientras se crean. Sabemos que OAS se trata de estándares, por lo que SwaggerHub puede defender firmemente estos estándares en tiempo real.

A los equipos les encantan dos cosas: los ejemplos y la reutilización. El primero permite a los equipos ver cómo se está uniendo una API mientras prueban la funcionalidad mediante llamadas y devoluciones. Estos servidores de prueba pueden mostrarle dónde son necesarias las optimizaciones dentro de su estructura. Por ejemplo, no querrá publicar una API con puntos finales que no coincidan con tipos de datos, objetos y matrices. Su API no funcionaría de manera efectiva si estos esquemas no fueran adecuados. En el frente de la reutilización, puede guardar componentes que pueden ser útiles dentro de otras especificaciones de API.

¿Qué más puedes hacer con SwaggerHub?

  • Acceso y gestión de equipos, incluida la delegación de propiedad del proyecto
  • Bifurcar, comparar y fusionar código
  • Seguimiento de problemas junto con el editor para un mejor contexto
  • Sincronización de definiciones de API con repositorios de origen y puertas de enlace

SwaggerHub es una forma poderosa de hacer que su proceso de diseño de API sea más inclusivo.

Swagger Tools: una potente suite de OpenAPI

Swagger es sinónimo de diseño sólido de API OAS, y familiarizarse con sus herramientas hará que el proceso sea mucho más fácil. Si bien los componentes de Swagger pueden no ser perfectos para principiantes, incluso los desarrolladores novatos apreciarán muchas de las opciones de código bajo de Swagger. Es posible que ni siquiera comience desde cero: Swagger proporciona instrucciones claras sobre cómo construir a partir de API existentes dentro de su documentación.

Si desea crear una API REST con la máxima compatibilidad, la especificación OpenAPI debería ser su guía.

Publicar un comentario

0 Comentarios