WebAPI - 自动生成包含所有可能响应的文档
WebAPI - auto generate documentation with all possible responses
我读过一篇文章 http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages，它工作正常。但我更愿意添加所有可能的响应和条件，这些响应将在何时发送。任何分析每个 WebAPI 方法的工具，找到所有有响应的地方，为什么会发生并自动创建关于它的文档？
即我有以下代码：
public HttpResponseMessage GetEditorialRequests()
{
SetUser();
try
{
var r_list = _service.RequestList(user.Id);
if (r_list.Count > 0)
{
var list = mapper.Map<List<SmartphonePhotographerRequestElementApiModel>>(r_list);
return Request.CreateResponse<List<SmartphonePhotographerRequestElementApiModel>>(HttpStatusCode.OK, list);
}
else
return Request.CreateResponse(HttpStatusCode.NoContent);
}
catch (PixlocateBusinessLogic.NoSmartphonePhotographerLocationException)
{
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, new HttpError("User does not have any locations") { { "CustomStatusCode", 466 } });
}
}
我想要一份描述该方法的文档 returns:
- StatusCode = 200 和方法成功完成并找到元素时的元素列表
- StatusCode = 204 当方法成功完成且未找到任何元素时
- 未找到位置时 StatusCode = 400（获取编辑请求的条件）以及消息和 CustomStatusCode 的详细响应
你试过了吗Swagger (and Swashbuckle)？
招摇
Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.
虚张声势
Seamlessly adds a Swagger to WebApi projects! Combines ApiExplorer and Swagger/swagger-ui to provide a rich discovery, documentation and playground experience to your API consumers. In addition to its Swagger generator, Swashbuckle also contains an embedded version of swagger-ui which it will automatically serve up once Swashbuckle is installed. This means you can complement your API with a slick discovery UI to assist consumers with their integration efforts. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API!
我在很多项目中都用到了它们，非常好用而且非常强大。
我读过一篇文章 http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages，它工作正常。但我更愿意添加所有可能的响应和条件，这些响应将在何时发送。任何分析每个 WebAPI 方法的工具，找到所有有响应的地方，为什么会发生并自动创建关于它的文档？
即我有以下代码：
public HttpResponseMessage GetEditorialRequests()
{
SetUser();
try
{
var r_list = _service.RequestList(user.Id);
if (r_list.Count > 0)
{
var list = mapper.Map<List<SmartphonePhotographerRequestElementApiModel>>(r_list);
return Request.CreateResponse<List<SmartphonePhotographerRequestElementApiModel>>(HttpStatusCode.OK, list);
}
else
return Request.CreateResponse(HttpStatusCode.NoContent);
}
catch (PixlocateBusinessLogic.NoSmartphonePhotographerLocationException)
{
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, new HttpError("User does not have any locations") { { "CustomStatusCode", 466 } });
}
}
我想要一份描述该方法的文档 returns:
- StatusCode = 200 和方法成功完成并找到元素时的元素列表
- StatusCode = 204 当方法成功完成且未找到任何元素时
- 未找到位置时 StatusCode = 400（获取编辑请求的条件）以及消息和 CustomStatusCode 的详细响应
你试过了吗Swagger (and Swashbuckle)？
招摇
Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.
虚张声势
Seamlessly adds a Swagger to WebApi projects! Combines ApiExplorer and Swagger/swagger-ui to provide a rich discovery, documentation and playground experience to your API consumers. In addition to its Swagger generator, Swashbuckle also contains an embedded version of swagger-ui which it will automatically serve up once Swashbuckle is installed. This means you can complement your API with a slick discovery UI to assist consumers with their integration efforts. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API!
我在很多项目中都用到了它们，非常好用而且非常强大。