Include validation errors in swagger documentation?

Codit / practical-api-guidelines

Practical guidelines for building & designing APIs with .NET.

MIT License

16 stars 5 forks source link

Include validation errors in swagger documentation? #111

Open pietersap opened 5 years ago

pietersap commented 5 years ago

Each controller can also return a validation error, status code 400. Should we also include this in the swagger documentation, for completeness? In a similar way that the OK200 and ERROR500 status codes are documented here below.

        [HttpGet(Name = Constants.RouteNames.v1.GetCustomizations)]
        [SwaggerResponse((int)HttpStatusCode.OK, "List of players")]
        [SwaggerResponse((int)HttpStatusCode.InternalServerError, "API is not available")]
        public async Task<IActionResult> GetCustomizations()

fgheysels commented 5 years ago

Imo, yes.

MassimoC commented 5 years ago

probably we should update the guidance of the Level 1 saying that for every implemented status code, a swagger response attribute should be added.

pietersap commented 5 years ago

Agreed