Uso de Swagger en una ASP.NET Core 2 Web API (II)
En la anterior entrada veíamos como agregar Swagger a nuestra Web API para nutrirla de información de ayuda.
Esto es especialmente útil para aquellos desarrolladores que deseen utilizar nuestra Web API.
No obstante, a veces la información que agregamos puede resultar escasa, por lo que a continuación y en esta entrada, vamos a ver como agregar más información a nuestra Web API.
Lo que haremos básicamente será crear comentarios XML a nuestro código, para que sean consumidos por Swagger y puedan ser agregados a la información mostrada por Swagger.
Así que la primera acción obligada es habilitar la generación del documento XML que se generará al compilar nuestra solución, y que por defecto está deshabilitado.
Una vez realizado esto, vamos a abrir Startup.cs y vamos a agregar las siguientes instrucciones dentro public void ConfigureServices(IServiceCollection services) y concretamente dentro de AddSwaggerGen.
public void ConfigureServices(IServiceCollection services) { services.AddMvc(); // Register the Swagger generator, defining one or more Swagger documents services.AddSwaggerGen(swagger => { var contact = new Contact() { Name = SwaggerConfiguration.ContactName, Url = SwaggerConfiguration.ContactUrl }; swagger.SwaggerDoc(SwaggerConfiguration.DocNameV1, new Info { Title = SwaggerConfiguration.DocInfoTitle, Version = SwaggerConfiguration.DocInfoVersion, Description = SwaggerConfiguration.DocInfoDescription, Contact = contact } ); // Set the comments path for the Swagger JSON and UI. var xmlPath = Path.Combine(AppContext.BaseDirectory, "WebApiEasySwagger.xml"); swagger.IncludeXmlComments(xmlPath); }); }
Por último, vamos a acudir al código fuente de nuestro controlador y vamos a agregar comentarios XML al código.
Una vez realizado todo esto, compilaremos nuestro proyecto de Web API y lo ejecutaremos.
Si accedemos a la ayuda de Swagger, veremos que los comentarios XML aparecen ahora en la documentación de Swagger.
Espero que estos pequeños consejos te ayuden a programar mejores Web APIs.
Podrás acceder al código fuente de este ejemplo en mi repositorio de GitHub en este enlace.
¡Happy Coding!