使用Swagger记录ASP.NET Web API

在本文中，我将介绍一些可以为ASP.NET Web API生成文档的方法。在开发Web API的过程中你会发现，默认模板已经包含了为可实现的API 生成文档的功能。这一点在authme.ws中有一个实例。

入门

有关如何使用Swagger生成ASP.NET的Web API文档的文章已经有很多了（通过一个叫做Swashbuckle的NuGet包，你可以轻松地对此进行集成），但我需要不那么“动态”的东西——因为实际上我需要“静态的”文档用来描述我们在生产过程中有哪些提升，并将此提供给评估工作。

传统的文档（例如Sandcastle Help File Builder）显然是不能满足我们的要求的，因为它记录的是托管代码，而不是更重要的API接口和运行时模型。

幸运的是，有一个工具集很好地支持了Swagger，叫做Swagger Codegen，它可以生成客户端代码来使用API，即生成静态HTML的能力。然而无奈的是，我找不到.NET可以用于Swagger Codegen的端口，所以我强行做了个尝试：使用Maven和最新的JDK从源代码编译Java二进制文件。

所需进行的准备

首先你要有一个可以在IIS或IIS Express中启动的Web API站点。理想情况下，你要做的是将前面提到的Swashbuckle NuGet包集成到你现有的（或新建立的）Web API项目中。安装完成后，你只需更改项目设置以生成XML说明文件（这不是必需的步骤，但很有用 - 请参阅下面的图像），然后配置App_Startup文件夹下的SwaggerConfig.cs文件。

启用XML注释输出，

Swashbuckle NuGet包（Swashbuckle和Swashbuckle.Core）

下面是一个非常简短（最简单）的SwaggerConfig实现，在此我移除了其中的注释：

public class SwaggerConfig
{
   public static void Register()
   {
       var thisAssembly = typeof(SwaggerConfig).Assembly;
       GlobalConfiguration.Configuration.EnableSwagger(c =>
       {                      
          c.SingleApiVersion("v1", "API Services");
          c.IncludeXmlComments(GetXmlCommentsPath());
       })
      .EnableSwaggerUi(c =>
       {
       });            
   }
   private static string GetXmlCommentsPath()
   {
       var path = String.Format(@"{0}bin\Services.XML", AppDomain.CurrentDomain.BaseDirectory);
       return path;
   }}

进行编译运行后，能够看到Swagger UI，如下所示：

这是十分令人印象深刻的动态文档UI。

这里的关键在于其所生成的JSON中。此JSON可以通过文本框中的URI访问。在我的项目中这个URI是：http://localhost:2218/swagger/docs/v1

(swagger.json)

Swagger JSON示例

转换为静态文档

继续来看Swagger Codegen。这里你需要一个Java JDK的副本（译注：a copy of the Java JDK，可以理解为在你的电脑中需要安装一个Java JDK环境）。在安装JDK之后，你需要确保JAVA_HOME环境变量的目录是正确的（而不是运行时目录）并安装/提取Maven二进制文件。

我使用了最新的JDK（1.8，32位），它具有以下目录：C:\Program Files(x86)\Java\jdk1.8.0_51。我将Maven安装了在Java目录中，并把它（特别是bin目录）添加到系统路径(System Path)中：

准备好之后，你需要将Swagger Codegen代码解压缩到本地目录中，然后在命令提示符（cmd）中移至该目录，然后键入mvn package命令，并等待Maven抓取完所有所需的包：

等待Maven抓取到所有的包

一旦编译成功，执行编译后的jar文件就简单了。根据我的配置，我把提取的swagger文件放在C:\Tools中。打开命令提示符并移至以下位置：

C:\Tools\swagger-codegen-master\

此时若要为你的API生成静态HTML文档，请参照以下语法格式：

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -ihttp://localhost:2218/swagger/docs/v1 -l html

然后就会为你的Web API生成一个直观的静态文档：

一个nice的静态HTML文件，您可以“打印”为PDF，或复制粘贴到Word中

故障排除

如果你生成的.json产生这样的空对象：

“Object”:{ 
“type”:“object”,
“properties”:{} 
}

这可能是由于相关程序在响应时缺乏有关于数据类型的足够的信息。例如，若采取了以下的控制器定义：

public class VersionController:ApiController
{   private readonly IVersionQuery _query;
    public VersionController(IVersionQuery query)
    {
        Guard.That(query, "query").IsNotNull();
        _query = query;
    }    [AllowAnonymous]
    public IHttpActionResult Get()
    {
        var version = _query.GetVersion();
        return Ok(version);
    }
}

在这里便丢失了一个提供返回类型的属性。可以像这样来装饰Get()的实现：

[ResponseType(typeof(VersionInfo))]