Documentar servicios con swagger: implementation notes y response class

Hasta ahora puedes encontrar diferentes cosas en este blog para una configuración básica de swagger como herramienta para documentar tus APIs.

Con esta entrada vas a darle algo mas de riqueza a la documentación sobre tus servicios. Con aspectos como “Implementation Notes” o el tipo devuelto por la respuesta en caso de tener 200 o diferentes códigos de error.

Hasta ahora el aspecto de tu servicio con mi entrada sobre “Cómo documentar un servicio con swagger y summary” era el siguiente:

Aquí de momento solo se aprecia el método Get, la uri, una breve descripción y el Content Type de la respuesta.

En caso de tener un servicio con parámetros como muestro en la anterior entrada, también podías ver una descripción sobre los parametros, si son opcionales o requeridos, su tipo de dato y si forman parte del path o del body.

Tras esta entrada, podrás ver un aspecto como el siguiente:

Aquí ya puedes ver 3 grandes áreas, las notas de la implementación donde se puede añadir cualquier matiz que se quiera concretar, el tipo de objeto devuelto, el cual a su vez se puede documentar para cada una de sus propiedades y las respuestas y sus tipos en caso de respuestas de error.

Para conseguir esto el mecanismo es muy sencillo.

Implementation notes

En esta primera mejora he introducido la sección <remarks></remarks> en el XML que documenta el método,  todo lo incluido en esta sección será incluido en las “implementation notes” en swagger.

Es importante destacar que si queremos que se realice un salto de línea en swagger, necesitamos incluir al final de cada línea en el código, en “remarks”, dos espacios en blanco. De lo contrario, todas las líneas se concatenarán sin salto de línea.

Response class

Ahora el punto importante es “SwaggerResponse”, con esté annotation podemos especificar el código http al que queremos hacer la referencia en la documentación, la descripción, y el modelo devuelto en caso de este tipo de respuesta.

En swagger además este objeto devuelto tenía también documentadas sus propiedades, esto es gracias a documentación XML de sus propiedades, a través de summary, de igual forma que se hace con los métodos del controlador.

Response messages

Por último, la zona en la que especificamos los posibles tipos de mensajes de error se documenta también con swaggerReponse, indicando de igual manera el código de error Http que se pretende documentar, una descripción y el modelo devuelto.

Con toda esta información, el método quedaría como sigue:

Si te has fijado con detalle, las areás de modelo tiene una opción para seleccionar un “example value”, donde podríamos definir un ejemplo típico de las propiedades del objeto, pero esto se quedará para otra entrada.

Entradas relacionadas:

¿Qué es swagger?

Cómo instalar swagger en tu webapi.

Cómo documentar un servicio con swagger y summary.

Cómo habilitar autenticación OAuth en swagger.

Cómo instalar y configurar swagger en .Net Core usando OAuth2

Deja un comentario