4.5.3 Generando la página de documentación

Por último configuramos el proyecto para que el compilador genere el archivo xml con los comentarios de los servicios y de modelo.

Configurando los comentarios XML desde Visual Studio

1. Da clic derecho sobre la solución y elige la opción Propiedades

2. Selecciona la opción Compilación y marca la opción Archivos de documentación XML. Verifica que la ruta sea bin\Debug\netcoreapp2.1\CaducaRest.xml

3. Guarda los cambios

En nuestro archivo Startup.cs, en el método ConfigureServices, le indicamos a Swagger que tome la ruta de nuestro xml para generar la documentación en base al xml.

Startup.cs

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
         services.AddSwaggerGen(c =>
         {
             c.SwaggerDoc("v1", new Info { Title = "Api Caduca REST", 
                     Version = "v1" });
             //Obtenemos el directorio actual
             var basePath = AppContext.BaseDirectory;
             //Obtenemos el nombre de la dll por medio de reflexión
             var assemblyName = System.Reflection.Assembly
                           .GetEntryAssembly().GetName().Name;
             //Al nombre del assembly le agregamos la extensión xml
             var fileName = System.IO.Path
                           .GetFileName(assemblyName + ".xml");
             //Agregamos el Path, es importante utilizar el comando
             // Path.Combine ya que entre windows y linux 
             // rutas de los archivos
// En windows es por ejemplo c:/Umostarsuarios con / 
             // y en linux es \usr con \
             var xmlPath = Path.Combine(basePath, fileName);
             c.IncludeXmlComments(xmlPath);
         }
    }
}

Vamos a cambiar la configuración para que la página de Inicio sea la de swagger

1. En las propiedades del proyecto (Clic derecho sobre el proyecto y elige la opción Propiedades)

2. Selecciona la opción Depurar en la opción Iniciar explorador escribe swagger la cual es la página por defecto para mostrar los servicios disponibles de tu aplicación

Corre el proyecto y verás una página con la lista de servicios disponibles.

La página te muestra los servicios disponibles en cada controlador. En este caso muestra los de Categorias y el de Values que fue creado por default.

Al dar clic en cada tipo de servicio te muestra la documentación y una opción para probarla

Al final te muestra los modelos si le das clic al modelo puedes ver la descripción de cada modelo

Si no deseas que se vea la descripción de los modelos en la parte inferior, porque ya se muestra en el modelo de cada petición agrega este código: c.DefaultModelsExpandDepth(-1);

Startup.cs

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
   //Código
   app.UseSwaggerUI(c =>
       {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "Api Caduca REST");
            c.RoutePrefix = string.Empty;
            c.DefaultModelsExpandDepth(-1);
       });

Probar el servicio POST

1. Da clic sobre el método POST. Te muestra un json de ejemplo y los estados que regresa tu servicio. Si das clic en la opción Model puedes ver la descripción de cada atributo

2. Da clic en el botón Try it out 3. Teclea los datos de la categoría en mi caso tengo la tabla vacía 4. En la opción Parameter content type selecciona la opción application/json para indicar que enviaremos un archivo json 5. Da clic en el botón Execute

Verás que regresa el estatus 201 con la categoría creada

Probar el servicio GET

1. Da clic sobre el método GET

2. Presiona el botón Try it out

3. Da clic en el botón Execute

4. Puedes ver que regresa el Estatus 200 con los datos de la categoría creada

Probar el servicio PUT

1. Da clic sobre el método PUT

2. Da clic en el botón Try it out

3. En id teclea el Id de la categoría que deseas modficar en este ejemplo es la 1

4. Teclea los datos de la categoría en formato Json

5. En Parameter content type selecciona application/json

6. Da clic en el botón Execute

Puedes ver que regresa un status 204

Probar el servicio DELETE

1. Da clic sobre el método DELETE

2. Da clic en el botón Try it out

3. Tecle el id de la categoría que deseas borrar en este caso el 1

4. Da clic en el botón Execute

Puedes ver que regresa el estatus 200 con los datos de la categoría borrada

Configurando los comentarios XML desde Visual Studio for mac

1. Da clic derecho sobre la solución y elige la opción Opciones

2. Selecciona la opción Compilar -> Compilador, marca la opción Generar documentación de XML y da clic en Aceptar

3. Da clic en la opción Ejecutar -> Configuraciones -> Default 5. Realiza un scroll hacia abajo y en URL teclea swagger para que se vaya a la página http://localhost:5000/swagger