Anterior

Siguientes

Enriquecimiento de la documentación de OpenAPI con comentarios XML y anotaciones

Completado

Swagger UI le permite interactuar con los recursos de la API y visualizarlos sin necesidad de acceder al código fuente. La representación gráfica de la API se genera automáticamente de la especificación OpenAPI y facilita que otros desarrolladores compilen aplicaciones que usan las API.

Swagger UI visualiza las operaciones y métodos claramente, tal como se muestra en la siguiente imagen.

Swagger UI también le permite interactuar e incluso probar cada operación.

Crear automáticamente la documentación de API con las herramientas Swashbuckle y Swagger puede ayudar a terceros a entender los recursos de la API. Pero ¿qué ocurre si quiere ir un poco más allá y proporcionar información más detallada? Si usa una API por primera vez, le interesará tener la mayor información posible.

Comentarios XML

Puede crear documentación para el código incluyendo comentarios XML. Normalmente, colocará estos comentarios directamente antes del bloque de código sobre el que está comentando.

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

Aquí tiene los nodos XML en uso:

• summary: Un resumen general de lo que es o hace el método, clase o campo.
• comentarios: más detalles sobre el método, la clase o el campo.
• param: Un parámetro al método y lo que representa.
• returns: Una descripción de lo que devuelve el método.

Cuando active los comentarios de XML, la herramienta Swashbuckle puede incluir los comentarios de documentación XML en la documentación de OpenAPI y le permite verla en Swagger UI.

Anotaciones de datos

Lo mismo ocurre con las anotaciones de datos. Solo tiene que agregar una anotación en el modelo y Swagger amplia la documentación de API para que la incluya.

Por ejemplo, si agrega la siguiente anotación a un controlador:

[Produces("application/json")]

... puede ver la información agregada en Swagger UI.

Sugerencias

Hay varias anotaciones de datos que debe usar al describir la API.

• Identifique qué content-types controla la API en las solicitudes y respuestas. Los atributos siguientes especifican que la API solo debe usar el tipo de contenido application/json en ambas direcciones.

  [Produces("application/json")]
  [Consumes("application/json")]
  

• Identifique los posibles códigos de respuesta HTTP que se pueden devolver al cliente que realiza la llamada. El atributo siguiente muestra una API que podría devolver un error de tipo 404 No encontrado.

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  La API puede generar un conjunto estándar de códigos de respuesta; en ese caso, puede usar el atributo siguiente para especificar 200, 400 y 404 en lugar de especificar cada uno individualmente. Más información sobre el uso de las convenciones de la API web.

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• Genere operationId para mejorar significativamente la experiencia de consumo de la API, incluida la documentación, la generación de código y la integración con otros servicios. Puede generar automáticamente operationId incluyendo la propiedad Name en el filtro de verbo HTTP.

  [HttpGet("{Height}/{Width}", Name="GetPrice")]
  

Continuar