Thanks for your feedback!
EDIT
Interface Completeness
La documentación deficiente es uno de los problemas más frecuentes que enfrentan los consumidores de APIs. Por ejemplo, los recursos a menudo no tienen una descripción que nos muestre para qué sirven y las solicitudes a menudo fallan sin que la devolución nos diga qué debemos hacer para completar la llamada. Los problemas de este tipo se pueden evitar si existe una gobernanza que establezca que las APIs solo se pueden implementar en un entorno de producción si su documentación es suficiente.
Sensedia desarrolló la función Interface Completeness precisamente para ayudarlo a visualizar qué tan completa es la documentación de una API.
No hay una pantalla específica para Interface Completeness; se muestra en la esquina superior derecha de la pantalla Overview de una API:
La función analiza el Swagger de la API y compara la cantidad de campos que tiene con la cantidad total de campos que podrían incluirse en un archivo Swagger. Según esta comparación, muestra un porcentaje para representar el grado de completud del archivo. Además, en función de los problemas detectados, ofrece sugerencias para que pueda mejorar la documentación (lee más sobre esto más abajo).
Con esto, puede:
-
utilizar el porcentaje de completud como requisito para promover las APIs de una etapa de workflow a otra (ver más sobre esto a continuación);
-
asegúrarse de que la API que está exponiendo al público en su Portal de Desarrolladores esté suficientemente documentada (puede elegir exhibir las APIs en el Portal en la pantalla Overview de la API).
|
¿Cómo puedo interpretar el porcentaje de Interface Completeness? Para llegar al porcentaje final, comparamos la cantidad de campos que tiene su archivo Swagger con la cantidad total de campos que podrían incluirse. Utilizando nuestra experiencia en APIs, asignamos diferentes pesos a los campos para valorar los elementos que son más importantes (por ejemplo, incluir códigos de retorno HTTP es más importante que describir el error). También validamos el formato de algunos campos, por ejemplo:
De todos modos, el resultado final es cuantitativo, no cualitativo: proporciona una medida de completud de la documentación, no dice nada de la calidad del diseño. Por ejemplo, verificamos si su API tiene una descripción, no si la descripción se adapta bien a lo que hace la API o si es clara para el consumidor. Puede y debe usar este porcentaje como una etapa de verificación antes de exponer la API, asegurándose de que el Swagger esté suficientemente completo, pero no como una validación de la calidad de la API. En cuanto al valor porcentual que podría funcionar como un umbral de completud, esto depende de su estrategia de APIs y de los objetivos de cada API que diseñe. Es por eso que puede definir cualquier valor que desee para Interface Completeness como un requisito para promover las APIs de una etapa de workflow a otra (vea más sobre esto a continuación).
|
Sugerencias para mejorar el archivo Swagger
La herramienta también muestra sugerencias de mejora después de verificar los campos del archivo Swagger. Para verlas, haga clic en Suggestions, debajo del porcentaje.
Puedes hacer modificaciones usando el editor Swagger (ver más información al respecto aquí).
Después de realizar los cambios y guardar su API como una nueva revisión, la evaluación de completud se realiza nuevamente.
Ejemplo de uso
Creamos una API con descripción y ruta base, pero no incluimos ningún recurso, lo que generó un bajo nivel de completud:
Luego, incluimos estos dos recursos:
Usando el editor Swagger del Manager, incluimos los tipos de devolución de cada recurso, mensajes de error con los códigos de respuesta HTTP para cada recurso y descripciones de algunas propiedades del modelo. Nuestra API ahora está lista para ser expuesta:
Campos comprobados
Estos son los campos que la funcionalidad comprueba para evaluar la completud de la documentación de la API (recordando que hay diferentes pesos para cada uno):
| API | Recurso/Operación | Modelo |
|---|---|---|
|
|
|
Cómo utilizar Interface Completeness con Workflows
La función Workflows controla las etapas del desarrollo de APIs. Permite personalizar los requisitos para que una API sea promovida entre las etapas, lo que le da visibilidad y control del proceso de desarrollo de cada API.
Uno de los requisitos que se puede establecer es un porcentaje mínimo de Interface Completeness. En este caso, si define que solo las APIs con al menos un 85% de completud deben estar en la etapa «Production» y también incluye el requisito de que solo las APIs de esta etapa se pueden implementar en un entorno de producción, entonces efectivamente establece que las APIs solo se pueden implementar para el público con documentación satisfactoria.
Puede leer más sobre Workflows aquí.
Share your suggestions with us!
Click here and then [+ Submit idea]