[ASP.NET Web API] Generando páginas de ayuda y documentación

Posted on Actualizado enn


 

Hola a todos, un tema importante al crear nuestros servicios es documentarlos, y esta es una tarea bastante tediosa, sin embargo y para fortuna de muchos (me incluyo) ASP.NET Web API nos ayuda en esta labor generando una página de ayuda y una documentación con tan solo modificar un par de cosillas al proyecto.

Nota: El demo ha sido realizado con Visual Studio 2013, si tienen Visual Studio 2012 deben agregar el paquete Microsoft.AspNet.WebApi.HelpPage

Iniciemos, creamos una nueva aplicación ASP.NET Web Application y luego seleccionamos la plantilla Web API:

create web api

Ahora creamos un nuevo modelo:

public class Client
{
	[JsonProperty(PropertyName = "Id")]
	public int ClientId { get; set; }

	[JsonProperty(PropertyName = "Nombre")]
	public string Name { get; set; }

	[JsonProperty(PropertyName = "Apellido")]
	public string LastName { get; set; }

	[JsonProperty(PropertyName = "Ciudad")]
	public string City { get; set; }

	[JsonIgnore]
	public string Password { get; set; }
}

Luego añadimos un controlador, en este caso con el nombre ClientController, lo importante es añadir la información a cada método, ya que dicha información será utilizada para la documentación de cada acción:

public class ClientController : ApiController
{
	private AppContext db = new AppContext();

	/// <summary>
	/// Get all clients
	/// </summary>
	/// <returns>List of clients</returns>
	public IQueryable<Client> GetClients()
	{
		return db.Clients;
	}

	/// <summary>
	/// Get a client by Id
	/// </summary>
	/// <param name="id">Client id</param>
	/// <returns>One Client</returns>
	[ResponseType(typeof(Client))]
	public IHttpActionResult GetClient(int id)
	{
		Client client = db.Clients.Find(id);
		if (client == null)
		{
			return NotFound();
		}

		return Ok(client);
	}

	/// <summary>
	/// Update a Client
	/// </summary>
	/// <param name="id">Client id</param>
	/// <param name="client">Client to be updated</param>
	/// <returns>>Operation result</returns>
	public IHttpActionResult PutClient(int id, Client client)
	{
		if (!ModelState.IsValid)
		{
			return BadRequest(ModelState);
		}

		if (id != client.ClientId)
		{
			return BadRequest();
		}

		db.Entry(client).State = EntityState.Modified;

		try
		{
			db.SaveChanges();
		}
		catch (DbUpdateConcurrencyException)
		{
			if (!ClientExists(id))
			{
				return NotFound();
			}
			else
			{
				throw;
			}
		}

		return StatusCode(HttpStatusCode.NoContent);
	}

	/// <summary>
	/// Create a new Client
	/// </summary>
	/// <param name="client">Object Client</param>
	/// <returns>Operation result</returns>
	[ResponseType(typeof(Client))]
	public IHttpActionResult PostClient(Client client)
	{
		if (!ModelState.IsValid)
		{
			return BadRequest(ModelState);
		}

		db.Clients.Add(client);
		db.SaveChanges();

		return CreatedAtRoute("DefaultApi", new { id = client.ClientId }, client);
	}

	/// <summary>
	/// Delete a client by id
	/// </summary>
	/// <param name="id">Client id</param>
	/// <returns>Operation result</returns>
	[ResponseType(typeof(Client))]
	public IHttpActionResult DeleteClient(int id)
	{
		Client client = db.Clients.Find(id);
		if (client == null)
		{
			return NotFound();
		}

		db.Clients.Remove(client);
		db.SaveChanges();

		return Ok(client);
	}

	protected override void Dispose(bool disposing)
	{
		if (disposing)
		{
			db.Dispose();
		}
		base.Dispose(disposing);
	}

	private bool ClientExists(int id)
	{
		return db.Clients.Count(e => e.ClientId == id) > 0;
	}
}

Hasta el momento nada nuevo, pero si nos fijamos bien en la carpeta Areas, encontramos una carpeta HelpPage que será el área encargada de generar la documentación:

Area HelpPage

Allí vamos a la clase HelpPageConfig.cs y descomentariamos la siguiente línea que se encuentra en la función Register:

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Luego en las propiedades del proyecto, en la opción Build, sección Output marcamos la casilla XML documentation file:

properties

Ahora si ejecutamos y seleccionamos la opción API del menú tenemos el listado de acciones con su descripción, y al seleccionar una en particular vamos al detalle de dicha acción:

doc 1

doc 2

Adicionalmente, si vamos a la ruta App_Data\XmlDocument.xml del proyecto, dicho archivo xml contiene la información que se está mostrando en pantalla!

Espero les sea interesante el post, saludos!

8 comentarios sobre “[ASP.NET Web API] Generando páginas de ayuda y documentación

    jeffersonaguilar escribió:
    11/19/2013 en 09:08

    Tan Gomoso con VS2013, jejejeje, uy si super tener nuestros servicios bien documentados. Saludos

      Julio Avellaneda respondido:
      11/19/2013 en 09:10

      jajajaj toca estar con lo último amigo! pero si es muy sencillo y útil documentarlos! Saludos.

    Juan Carlos Ruiz Pacheco escribió:
    11/19/2013 en 11:32

    Excelente, muy apropiado más que ahora la tendencia es exponer en APIs REST, me parece una herramienta excelente.

      Julio Avellaneda respondido:
      11/19/2013 en 13:46

      Gracias Juan por tu comentario, así es, además con el crecimiento de dispositivos móviles cada día rest toma más fuerza

    ElTavo escribió:
    11/19/2013 en 13:17

    Muy útil y muy sencillo de configurar, gracias!!

    oscar cordoba escribió:
    11/20/2013 en 11:08

    Excelente herramienta, muy buena para los que no somos muy amigos de sentarnos a documentar, por lo canson que puede ser. Gracias Julito por el aporte

      Julio Avellaneda respondido:
      11/20/2013 en 13:23

      Gracias Oscar, si la verdad el tema de documentación muchas veces no es para nada agradable🙂

      Saludos.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s