# 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

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP-Cmmp3awVQESH_Qul%2F-LP-CnjdXyv5hYhlG76O%2Fimage.png?alt=media\&token=494ca4b4-07ab-4ccb-94dc-5ca4614f779f)

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. 

{% code title="Startup.cs" %}

```csharp
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);
         }
    }
}
```

{% endcode %}

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 

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP49gbpAX-1PMz5xJuf%2F-LP4ACDvw3EPPZA_yhHq%2Fimage.png?alt=media\&token=0c9e5b4f-bd73-4a20-a434-a566da95c18b)

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

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP4H92lsbJXKB-lUFBH%2F-LP4J6oZ5sRAgbbHZS7r%2Fimage.png?alt=media\&token=b260cca1-b249-4ecd-bc77-e3e92581b598)

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

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP49gbpAX-1PMz5xJuf%2F-LP4BrHEutzK2rR22P1J%2Fimage.png?alt=media\&token=5abde755-321d-40d0-b107-01065b98f3b6)

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);`

{% code title="Startup.cs" %}

```csharp
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);
       });
```

{% endcode %}

### 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

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP49gbpAX-1PMz5xJuf%2F-LP4Duesu_OhqNPSLner%2Fimage.png?alt=media\&token=c7473710-8777-49fc-812d-fa6debd84e9e)

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**

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP49gbpAX-1PMz5xJuf%2F-LP4EFo-oumoj7Y3Lrqj%2Fimage.png?alt=media\&token=386578b0-c722-42c3-93a2-8f2e6ac0179c)

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

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP49gbpAX-1PMz5xJuf%2F-LP4F9DrqDTi1xkaBBdI%2Fimage.png?alt=media\&token=b207cc4f-baa1-452b-bdd8-0b7aec573e50)

### 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

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP49gbpAX-1PMz5xJuf%2F-LP4GzDhUDg295Lr7FfC%2Fimage.png?alt=media\&token=128906e2-eb77-46ca-ae97-440b51cd97ba)

### 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**

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP4H92lsbJXKB-lUFBH%2F-LP4K0P3MZgDwLoKx_GD%2Fimage.png?alt=media\&token=c9dc6715-706a-48b7-8490-bbf62025c968)

Puedes ver que regresa un status **204**

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP4H92lsbJXKB-lUFBH%2F-LP4Kn7nQx0dr8kQ-cQI%2Fimage.png?alt=media\&token=e6e9c7e7-5a63-4737-90ba-715446b83691)

### **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**

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP4H92lsbJXKB-lUFBH%2F-LP4LiRXZCMVE0FM9Wp7%2Fimage.png?alt=media\&token=cc6235a1-510b-46b0-b3a6-8619fd811e4a)

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

![](https://3731331968-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LKmGSg4qhizjqeDPHJC%2F-LP4H92lsbJXKB-lUFBH%2F-LP4LtVXOKYrKud8DZoP%2Fimage.png?alt=media\&token=adb36038-eee9-44e7-9f11-c51dc8c1229d)