Cómo documentar un servicio con swagger y summary.

Continúo la serie de entradas sobre swagger como herramienta para documentar tus APIs.

En anteriores entradas he escrito sobre cómo configurarlo para una documentación básica de un endpoint, con lo que apenas conseguirás darle una funcionalidad básica y disponer del tipo de verbo Http y parámetros recibidos o respuestas devueltas. También he escrito sobre cómo utilizarlo con autenticación basada en bearer token, OAuth, lo cual es vital para probar desde swagger una API con este mecanismo de seguridad.

Ahora voy a explicarte como añadir documentación sobre la funcionalidad que tu endpoint expone, permitiéndote reflejar en una frase su comportamiento. 

El aspecto de tu swagger con la configuración básica será algo como esto:

El nuevo aspecto que vas a lograr, tras aplicar esta entrada a swagger, es el siguiente:

Cómo puedes observar, para cada servicio, se ofrece una pequeña descripción de su funcionalidad.

Inicialmente tu controlador tendrá este aspecto, siendo el controlador con el que swagger da lugar a la primera imagen que tienes mas arriba, antes de incluir a documentación.

Lo primero que debes hacer es documentar en el código tus endpoints añadiendo la información XML summary en cada método de tu controlador.

Si sobre el método escribes “///” automáticamente se te creará una estructura apropiada para documentar el mismo, y solo deberás completar con la información que deseas.

Si lo aplicas por ejemplo al Put (por tener 2 parámetros y por tanto ser mas útil como ejemplo) obtienes el siguiente resultado:

Toda la información que ves con “///” ha sido autogenerada con tan solo escribir ///. Ahora puedes cambiar el contenido de la información para ser mas explicito si lo necesitas.

Si lo intentas con un método que devuelva un resultado, también se generará una sección return.


Swagger no usará está sección, aunque hay otras formas de especificar el tipo de objeto devuelto o los posibles errores, esto será contenido para otra entrada. Aún así es una buena práctica utilizarla sección returns y completarla para documentar tu código de cara a otros desarrolladores que pudiesen tener la necesidad de mantener el código en el futuro. Esta información además será utilizada por intelliSense cuando quieras usar un método, mostrándose en la ayuda de las opciones a medida que desarrollas.

A continuación necesitas que cuando tu proyecto compile, generé un XML a partir de esta documentación, que posteriormente podrá ser usado por swagger. Para ello hay que hacer click derecho sobre el proyecto que contiene las clases cuyos métodos quieres documentar, ir a la opción de propiedades y una vez ahí ir a la sección de “Compilación”. Aquí podrás encontrar un apartado sobre resultados, con un check relativo a “Archivos de documentación XML” que deberás marcar, indicando la ruta donde este XML va a ser generado en el proyecto.

Cuando compiles tu proyecto, se generará un archivo XML en la ruta App_Data de tu proyecto, llamado SwaggerWebApiHelp.XML. No debes preocuparte por su contenido, swagger se encargará de ello, pero es necesario especificar en la configuración de swagger donde está el archivo para ser consumido. En la anterior entrada sobre cómo configurarlo, hablo sobre estas posibilidades de configuración, que pueden encontrarse en el startup, global.asax o directamente en la clase que swagger configura, dependiendo de la decisión que tomes sobre cómo utilizarlo.

La decisión que yo he tomado en mis proyectos es usarlo directamente en el startup, inicialmente presenté una configuración básica como la siguiente:

Para añadir la documentación XML, esta configuración deberá ser extendida de la siguiente manera:

Si estas publicando tu aplicación en Azure o algún otro entorno deberás asegurarte de que tus archivos XML se despliegan junto al resto de tu código, de lo contrario, swagger mostrará en su interfaz un error 500 en lugar de mostrar, ni tan siquiera, la configuración básica que presentaba tus servicios y controladores.

No obstante para comprobar que todo está en orden, la prueba se puede llevar a cabo desde local, ejecutando tu proyecto y añadiendo /swagger a la url de tu webapi, siendo el resultado del código anteriormente documentado el siguiente:

Además la documentación XML en el caso del PUT incluye 2 parámetros que han sido documentados, por lo que si expandes este servicio, podrás ver dicha información sobre los parámetros necesarios.

En esta última imagen también puede verse como se indica si un parámetro forma parte de la URL (path) o del cuerpo de la petición (body), y su tipo de dato. A su vez para el body se está especificando que se trata de tipo de contenido json.

También disponemos de información sobre si los parámetros son requeridos u opcionales, ya que de ser opcionales, el placeholder “(required”) no se mostraría en los inputs para introducir los parámetros.

Documentando todos los servicios restantes, es como llegarás a obtener una interfaz de swagger como la que presento al principio de la entrada, estando cada uno de los servicios documentados con una pequeña descripción sobre su funcionalidad.

Espero que te sirva de ayuda, seguiré profundizando en futuras entradas sobre las posibilidades de uso de swagger desde C#, ya que aquí no termina la cosa.

Un saludo, y disfruta programando.

Deja un comentario