使用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))]

本文的版权归 极大似然 所有,如需转载请联系作者。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏bboysoul

ubuntu 使用snap包

什么是snap,snap是一种全新的软件包管理方式,它类似一个容器拥有一个应用程序所有的文件和库,各个应用程序之间完全独立。所以使用snap包的好处就是它解决了...

35220
来自专栏SpringBoot 核心技术

第四十三章: 基于SpringBoot & RabbitMQ完成TopicExchange分布式消息消费

409150
来自专栏陈仁松博客

【译】使用 dotnet watch 开发 ASP.NET Core 应用

介绍 dotnet watch 是一个开发阶段在源文件发生变动的情况下使用 dotnet 命令的工具。 当代码发生变动的时候可以用来执行编译,运行测试,或者发布...

49860
来自专栏小勇DW3

SpringBoot的自动配置原理过程解析

SpringBoot的最大好处就是实现了大部分的自动配置,使得开发者可以更多的关注于业务开发,避免繁琐的业务开发,但是SpringBoot如此好用的

15430
来自专栏葡萄城控件技术团队

Web API 持续集成:PostMan+Newman+Jenkins(图文讲解)

上篇文章我们已经完成了API测试工具选型,接下来是一系列周期性的开发测试过程:接口开发、检出代码、运行测试、记录结果、发送报告。为了快速发现问题,并减少重复过程...

21720
来自专栏python开发者

linux用户权限相关内容查看

linux用户权限相关内容查看 1   用户信息 创建用户一个名为 webuser 的账号,并填写相应的信息: root@iZ94fabhqhuZ:~# add...

26590
来自专栏云计算教程系列

如何使用killall和kill命令来停止进程

killall是一个基于名称终止系统上运行进程的工具。kill则是终止基于进程ID号(PID)的进程。kill和killall还可以向进程发送特定的系统信号。

23630
来自专栏NetCore

尝试使用Memcached遇到的狗血问题

乘着有时间,尝试下利用Memcached进行分布式缓存,其中遇到了不少问题及狗血的事情,开篇记录下,希望对您有帮助。 我之前的项目为:Asp.Net MVC4 ...

25650
来自专栏从零开始学自动化测试

pytest文档3-pycharm运行pytest

上一篇pytest文档2-用例运行规则已经介绍了如何在cmd执行pytest用例,平常我们写代码在pycharm比较多 写完用例之后,需要调试看看,是不是能正常...

45230
来自专栏帘卷西风的专栏

使用Cmake生成跨平台项目编译解决方案

    项目最近有需求在windows下面运行,我花了几周时间将linux的服务器移植到windows下面,目前已经能够正常运行服务器,目前又有了新需求,两边的...

65820

扫码关注云+社区

领取腾讯云代金券