使用 Swagger 记录 ASP.NET Web API

一则或许对你有用的小广告

欢迎加入小哈的星球 ,你将获得:专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

  • 新项目:《从零手撸:仿小红书(微服务架构)》 正在持续爆肝中,基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...点击查看项目介绍 ;
  • 《从零手撸:前后端分离博客项目(全栈开发)》 2 期已完结,演示链接: http://116.62.199.48/ ;

截止目前, 星球 内专栏累计输出 54w+ 字,讲解图 2476+ 张,还在持续爆肝中.. 后续还会上新更多项目,目标是将 Java 领域典型的项目都整一波,如秒杀系统, 在线商城, IM 即时通讯,权限管理,Spring Cloud Alibaba 微服务等等,已有 1900+ 小伙伴加入学习 ,欢迎点击围观

在本文中,我将介绍一些可以为 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] 中记录的问题帮助我做出了这一发现。