Header Ads Widget

Ticker

6/recent/ticker-posts

Más de 8 linters OpenAPI

 Especificación de OpenAPI

La especificación OpenAPI se puede utilizar para asegurar y acelerar el ciclo de vida de la API.

OpenAPI es ahora un método ampliamente adoptado para describir API web . Con ese hecho viene la presión para validar que estas especificaciones estén actualizadas, construidas con precisión y presentadas para un uso óptimo del desarrollador.

Especialmente con el cambio de OpenAPI v2 a v3, los desarrolladores pueden necesitar más ayuda para asegurarse de que su especificación coincida con la estructura y formato v3 actual Afortunadamente, hay muchas herramientas de código abierto que los desarrolladores pueden usar para ligar su especificación de API contra OpenAPI v3 , así como las mejores prácticas y reglas personalizadas.

En este artículo, mostramos linters de API de código abierto seleccionados que validan sus esquemas YAML y JSON para OpenAPI v3. Validar que las especificaciones de las API son ... especificadas ... brindará una mejor usabilidad, lo que lo ayudará a aprovechar al máximo su adopción de OpenAPI.

¿Qué es Linting? ¿Qué es API Linting?

Linting es el proceso de validación de código que se construye como se esperaba. Por lo general, esto se inicia contra un conjunto de reglas establecidas.

"Un linter o lint se refiere a herramientas que analizan el código fuente para marcar errores de programación, errores, errores de estilo y construcciones sospechosas" - lint (software)

Por lo tanto, la vinculación de API es el proceso de validación de API. Con OpenAPI ahora el formato de especificación más ampliamente adoptado para describir las API REST, los desarrolladores deben asegurarse de que sus esquemas cumplan con las especificaciones. Para ayudar con este proceso, hemos investigado 8 herramientas de código abierto gratuitas para ligar sus especificaciones de OpenAPI contra v3 .

En el momento de redactar este documento, las iteraciones de OpenAPI v3 disponibles son 3.0.0, 3.0.1 y 3.0.2. Como Smartbear describe , son "funcionalmente iguales"

1: especificidad

Haga cumplir las reglas de calidad en sus especificaciones de OpenAPI 3.0.x

Speccy asegura que una especificación es válida contra OpenAPI v3 y también la vincula contra ciertas reglas establecidas. Speccy se inicia con los comandos de la CLI utilizables: lintresolve, y serveOtras opciones amplían sus capacidades de formación de pelusa para seguir ciertas reglas; como -v, que detecta la verbosidad.

Una especificación de OpenAPI con información faltante aún puede considerarse técnicamente "válida". Por lo tanto, las reglas predeterminadas de Speccy aseguran que se llenen los campos de sentido común, como descripciones de parámetros o información de contacto. También permite la creación de reglas personalizadas. .

Además de la pelusa, Speccy tiene otras funciones útiles. Por ejemplo, su Resolvecomando combinará varios archivos en una sola especificación. Speccy también se integra con ReDoc para visualizar la documentación de la API. Con toda esta facilidad de uso del desarrollador, Speccy es un conjunto de herramientas útil que va más allá de la simple validación de especificaciones.

2: oas-kit

Una utilidad de OpenAPI para convertir / resolver / validar / lint

Oas-kit es una utilidad de código abierto para convertir las definiciones de Swagger 2.0 a OpenAPI 3.0 y validar y vincular dichos documentos. Basado en una tecnología similar a Speccy, el paquete oas-linter proporciona un conjunto sencillo de reglas para el linting de API. Puede ver la documentación de Opciones aquí para obtener parámetros de objetos específicos.

3: zally

Un linter OpenAPI 2 y 3 minimalista y fácil de usar

Mantenido por Zalando, zally es una herramienta de código abierto para vincular API con OpenAPI v2 y v3. De fábrica, zally validará las API según las pautas REST de Zalando , sin embargo, esto se puede reconfigurar si es necesario. Zallly viene equipado con una variedad de opciones de implementación: API RESTful, CLI y una interfaz web.

4: espectral

Un linter de objetos JSON flexible con compatibilidad con OpenAPI v2 y v3

Un aspecto clave de Spectral, el linter desarrollado por Stoplight , es su flexibilidad. Spectral te permite crear reglas personalizadas para lint objetos JSON. Estas reglas se pueden desarrollar para aplicar a ciertas partes de los objetos JSON. Aunque la personalización es posible, Spectral puede aprovechar los conjuntos de reglas existentes para validar y ligar las versiones 2 y 3 de OpenAPI. Los dos componentes principales de Spectral son reglas y funciones , que generan efectivamente una "guía de estilo flexible y personalizable para sus objetos JSON". Para una usabilidad aún mayor, Taylor Barnett también ha construido un Spectral Bot que crea una especificación de OpenAPI dada una solicitud de extracción de Github.

5: openapi-pelusa

Linter de OpenAPI v3 con características para usuarios de Visual Studio

Openapi-lint proporciona un método para convertir entre OpenAPI v2 y v3, y ofrece la capacidad de validar y filtrar documentos OpenAPI 3.0.x. Openapi-lint es una extensión útil para los usuarios de Microsoft Visual Studio (VS), ya que viene preconfigurada con comandos VS.

6: piloto abierto

Node.js linter para especificaciones de OpenAPI

Desarrollado por Braintree, openapilint es una utilidad de código abierto que utiliza Node.js para validar las API con el estándar de especificación OpenAPI. Toma un esquema o objeto JSON como entrada, lo analiza con este conjunto de reglas predeterminado y responde con mensajes de error útiles. Aunque openapilint comparte algunas cualidades con otros validadores de esquemas JSON, supuestamente va "más allá de esos validadores al apuntar a los problemas comunes específicos de OpenAPI".

7: validador de especificaciones de OpenAPI

Validación sencilla de OpenAPI v2 y v3

Escrito en Python, el validador API abierta Spec biblioteca valida una especificación API abierta para ambos v2 y v3. Puede validar una especificación directamente o especificando una URL. La herramienta está desarrollada por Artur Maciag y publicada bajo Apache v2.

Un comando para validar una especificación usando el validador de especificación de OpenAPI tiene el siguiente aspecto:

from openapi_spec_validator import validate_spec

validate_spec(spec_dict)

8: ovalado

CLI para la validación de documentos de la especificación OpenAPI.

Los desarrolladores que quieran una herramienta de validación de especificaciones OpenAPI simple y programática disfrutarán de oval, una utilidad mantenida por Jeremy Whitlock de Google. Está construido sobre Sway y brinda una cobertura completa de la OEA. "Los planes para el óvalo son proporcionar una experiencia similar a eslint para la validación de la OEA en el futuro".

Algunos ejemplos de comandos de CLI son los siguientes:

USAGE
  $ oval validate LOCATION

ARGUMENTS
  LOCATION  The path/URL to the OAS document being validated

OPTIONS
  -N, --no-color            turn off colored output
  -j, --json                output results as JSON
  -p, --print-success       print message for success
  -w, --warnings-as-errors  treat warnings as errors
Por qué debería diseñar API según las especificaciones

Menciones honoríficas:

¿Conoce alguna herramienta de linting OpenAPI útil? ¡Comenta abajo!

Opciones para el revestimiento de OpenAPI

OpenAPI tiene muchos beneficios , sin embargo, no tiene mucho sentido adoptar el estándar si no se hacen garantías de calidad. Para los desarrolladores de API REST que usan OpenAPI, las utilidades de linting ayudan a diluir el dolor. Tener una herramienta de este tipo en el ciclo de vida continuo de creación y publicación ciertamente podría ayudar a las organizaciones a mantener una gran cantidad de servicios impulsados ​​por OpenAPI.

Linting asegurará que los metadatos, servidores, rutas, parámetros, así como los cuerpos de solicitud y de respuesta, se representen con precisión. Una vez validadas con API linting con toda su fuerza, las definiciones de OpenAPI realmente pueden alcanzar su máximo potencial.

Por supuesto, existen herramientas prácticas de linting para todos los lenguajes de programación, como CSS LINT , JSHint , JSLint y Pylint . Los desarrolladores de API que buscan específicamente validadores de esquemas JSON también pueden beneficiarse de los marcadores JSONLint , joi o jsonschema ; estas herramientas pueden garantizar que JSON se valide y se formatee correctamente.

Recursos

Publicar un comentario

0 Comentarios