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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
/// <summary> /// Gets the logged user view model in order to edit the own profile. (TO DO Antiforgery) /// </summary> /// <remarks> /// 200 - Returns: The logged user view model /// 401 - invalid_grant /// 400 - Error Code 8 (Conflict): Error when init logged user (authorize was successful instead) /// 400 - Error code 13 (Parameter is null): Any method hasn't required parameters in backend flow (Notify in order to solve the issue) /// </remarks> [Authorize] [Route("GetProfile")] [HttpGet] public HttpResponseMessage GetProfile() { return Request.CreateResponse(System.Net.HttpStatusCode.OK, userService.GetUserVM()); } |
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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
/// <summary> /// Gets the logged user view model in order to edit the own profile. (TO DO Antiforgery) /// </summary> /// <remarks> /// 200 - Returns: The logged user view model /// 401 - invalid_grant /// 400 - Error Code 8 (Conflict): Error when init logged user (authorize was successful instead) /// 400 - Error code 13 (Parameter is null): Any method hasn't required parameters in backend flow (Notify in order to solve the issue) /// </remarks> [Authorize] [Route("GetProfile")] [HttpGet] [SwaggerResponse(200, "The logged user view model", typeof(EditUserVM))] public HttpResponseMessage GetProfile() { return Request.CreateResponse(System.Net.HttpStatusCode.OK, userService.GetUserVM()); } |
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.
|
1 2 3 4 5 6 7 8 |
/// <summary> /// Gets or sets the name. /// </summary> /// <value> /// The name. /// </value> [Display(ResourceType = (typeof(UserMessages)), Name = "TXT_Name")] public string Name { get; set; } |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
/// <summary> /// Gets the logged user view model in order to edit the own profile. (TO DO Antiforgery) /// </summary> /// <remarks> /// 200 - Returns: The logged user view model /// 401 - invalid_grant /// 400 - Error Code 8 (Conflict): Error when init logged user (authorize was successful instead) /// 400 - Error code 13 (Parameter is null): Any method hasn't required parameters in backend flow (Notify in order to solve the issue) /// </remarks> [Authorize] [Route("GetProfile")] [HttpGet] [SwaggerResponse(200, "The logged user view model", typeof(EditUserVM))] [SwaggerResponse(400, "Bad request (see Implementation Notes)", typeof(AppError))] [SwaggerResponse(401, "invalid_grant. Error token authentication", typeof(string))] public HttpResponseMessage GetProfile() { return Request.CreateResponse(System.Net.HttpStatusCode.OK, userService.GetUserVM()); |
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:
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