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

Da clic derecho sobre la solución y elige la opción Propiedades
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
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

En las propiedades del proyecto (Clic derecho sobre el proyecto y elige la opción Propiedades)
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

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