使用 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 codegen 的称赞 Swagger 的工具集，它生成客户端代码以使用 API，对我来说 – 生成静态 HTML 的能力（由 [1] 提供）不幸的是我找不到 Swagger Codegen 的 .NET 端口，所以我硬着头皮使用 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，它可以通过文本框中的 URI 访问，在我的例子中是： http://localhost:2218/swagger/docs/v1 (swagger.json)

招摇的 JSON 示例

转换为静态文档

继续使用 swagger codegen ，您还需要 Java JDK 的副本。安装 JDK 之后（如果您还没有），您需要确保 JAVA_HOME 环境变量 正确到正确的目录（不是运行时目录）并安装/提取 Maven 二进制文件。

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

准备就绪后，您需要将 swagger codegen 代码提取到本地目录，在命令提示符下浏览到该目录并键入 mvn package：

稍等片刻，Maven 抓取所有包

编译成功后，执行编译后的 jar 文件是一件简单的事情。在我的例子中，我将提取的 swagger 文件放在 C:\Tools 中。打开命令提示符并浏览到以下位置：

C:\Tools\swagger-codegen-master\

要为您的 API 生成静态 HTML 文档，请使用以下语法：

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

这会生成一个很好的 Web API 静态文档：

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

故障排除

如果您生成的 .json 生成一个空对象，如下所示：

“目的”： {
“类型”：“对象”，
“特性”： {}
}

这很可能是由于响应中缺少有关数据类型的足够信息。例如，采用以下示例控制器定义：


 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;
   }}

我们在这里缺少的是一个提供返回类型的属性，像这样装饰 Get() 实现：

[响应类型（类型（版本信息））]

[2]、[3] 中记录的问题帮助我做出了这一发现。

使用 Swagger 记录 ASP.NET Web API

入门

你需要什么

转换为静态文档

故障排除

相关文章