Swagger简易教程——Swashbuckle版

 

简介及准备

实用配置

1. 利用XML备注生成说明文档

2. 利用Swagger属性标签进一步丰富文档

3. 为从Request中直接获取的输入添加文档

4. 自定义Swagger的文档路径

---

简介及准备

Swagger 是一个可用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的规范和框架。本文将介绍如何使用Swashbuckle为你的Web API应用程序添加Swagger说明文档。

本文的示例代码使用了.NET Framework 4.6.1。首先，创建一个新的Web API应用程序，比如名为MyDemo.Api。之后，安装Swashbuckle Nuget package（本文安装的是5.6.0）。当其安装完成之后，会在App_Start目录下生成一个Swagger.config文件，此时启动该应用程序，并在浏览器中输入http://localhost:<port>/swagger，即可得到一个空白的API说明文档了。对于OWIN应用程序，用户可能还需要在AppBuilder构建函数体中添加以下代码才能激活Swagger文档。

SwaggerConfig.Register(httpConfiguration);

实用配置

1. 利用XML备注生成说明文档

首先，添加一个用于实验的Controller类，如右键点击Controllers目录 --> Add -> Controller... --> Web API 2 Controller -Empty --> IdentityController。之后，为IdentityController添加一个简单的方法，并为该方法添加XML注释，在Visual Studio中我们可以通过连续输入三个斜线（/）来快速生成XML注释模板。

/// <summary>
/// This is a demo controller.
/// </summary>
[RoutePrefix("api/identity")]
public class Ide