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 .
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: lint, resolve, y serve. Otras 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 errorsMenciones honoríficas:
- Analizador Kaizen OpenAPI
- Linter-swagger de Atom
- APIs.guru cita que se está desarrollando una API Linter
- Pelusa API
- APIDevTools swagger-parser
- Validador de IBM OpenAPI
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.
0 Comentarios
Dejanos tu comentario para seguir mejorando!