Skip to main content

Ayuda y herramientas

La Web API se documenta y prueba con Swagger / OpenAPI. El módulo Crono.WebApi integra Swashbuckle para generar la documentación interactiva a partir de los propios controladores, y Markdig para renderizar descripciones en Markdown.

Documentación interactiva (Swagger UI)​

El módulo expone una interfaz de Swagger UI donde puedes explorar los endpoints, ver sus modelos de petición y respuesta, y probarlos directamente desde el navegador (autenticándote con una credencial de API). La documentación se genera con:

  • Swashbuckle.AspNetCore.SwaggerGen — construye el documento OpenAPI a partir de los controladores.
  • Swashbuckle.AspNetCore.SwaggerUI — la interfaz web para explorar y probar.
  • Swashbuckle.AspNetCore.Annotations — anotaciones para enriquecer la documentación.
  • Markdig — renderiza descripciones escritas en Markdown.

Documentos por grupo​

La documentación no es un único listado gigante: se divide por grupo (WebApiGrupo). Cada grupo (finanzas, prestamo, identidad, persona, venta, recursoshumanos, configuracion, contenido, usuario, comun, plataforma) genera su propio documento OpenAPI, y cada documento incluye las versiones que ese grupo declara. Así el consumidor encuentra rápido los endpoints del área que le interesa.

Qué aporta cada endpoint a la documentación​

La calidad de la documentación depende de cómo se anoten los controladores:

  • [WebApiGrupo(WebApiGrupoNombres.X)] — ubica el endpoint en su documento.
  • [ApiVersion("...")] / MapToApiVersion("...") — versión que responde.
  • [ProducesResponseType(typeof(...), Status200OK)] — esquema de la respuesta y códigos posibles.
  • Comentarios XML de resumen (<summary>) — descripción legible, que puede incluir Markdown.
/// <summary>
/// Lista las funciones del asesor autenticado habilitadas para ruta de cobranza.
/// </summary>
[HttpGet("funciones"), MapToApiVersion("1")]
[ProducesResponseType(typeof(List<FuncionRutaDto>), Status200OK)]
[Permiso(RutasCobranzaPermisos.Ver)]
public Task<IActionResult> ObtenerFunciones(CancellationToken ct) { /* ... */ }

Clientes externos​

Como el documento OpenAPI es estándar, puedes:

  • Importarlo en Postman o Insomnia para armar una colección de pruebas.
  • Generar clientes (C#, TypeScript, etc.) con herramientas basadas en OpenAPI.
  • Probar con curl/HTTP, recordando enviar Accept: application/vnd.crono.v1+json y la credencial del esquema Api (ver Autenticación).
tip

Si un endpoint no aparece en Swagger, revisa que su controlador tenga un [WebApiGrupo(...)] con un nombre válido de WebApiGrupoNombres: sin un grupo reconocido, el endpoint existe pero no se documenta.