使用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的能力。不幸的是,我找不到Swagger Codegen ,所以我咬一咬牙,决定使用Maven和最新的JDK, 从源代码编译Java二进制文件。

你需要什么

你需要能够在IIS或IIS Express中可以启动的Web API站点。理想情况下,你要做的是将前面提到的Swashbuckle NuGet包集成到你现有的(或新的)Web API项目中。安装完成后,你只需更改项目设置即可生成注释XML文件(不是强制性步骤,但非常有用 - 请参阅下图),然后配置插入App_Startup文件夹下项目的SwaggerConfig.cs文件。

启用XML注释输出。

Swashbuckle NuGet packages(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);
    }
}

如果你编译并运行,你应该能够看到下面这个Swagger UI,如下所示:

非常非常令人印象深刻的动态文档UI。

这里的关键是在生成的JSON中,可以通过文本框中的URI访问,在我的情况下是: http://localhost:2218/swagger/docs/v1(swagger.json)

swagger 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产生这样的空对象:

“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))]

在写这篇文章的过程中,我从[2], [3]获得了帮助。

本文的版权归 人工智能资讯小编 所有,如需转载请联系作者。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏Rainbond开源「容器云平台」

【Rainbond最佳实践】Spring Boot框架配置MySQL

Spring Boot框架简化了新Spring应用的初始搭建以及开发过程,云帮支持平台部署Spring Boot类应用。

31710
来自专栏草根专栏

使用Identity Server 4建立Authorization Server (3)

上一部分简单的弄了个web api 并通过Client_Credentials和ResourceOwnerPassword两种方式获取token然后进行api请...

2956
来自专栏BestSDK

基于Docker的PHP开发环境

【编者的话】本文作者是Geoffrey,他是一个PHP的Web开发者,喜欢DevOps和Docker。本文主要介绍了如何使用Docker构建PHP的开发环境,文...

2309
来自专栏Java技术分享

基于Metronic的Bootstrap开发框架经验总结(7)--数据的导入、导出及附件的查看处理

在很多系统模块里面,我们可能都需要进行一定的数据交换处理,也就是数据的导入或者导出操作,这样的批量处理能给系统用户更好的操作体验,也提高了用户录入数据的效率。我...

1837
来自专栏云计算

使用Swagger记录ASP.NET Web API

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

2197
来自专栏Laoqi's Linux运维专列

Ansible 基础搭建配置

956
来自专栏Golang语言社区

Golang基于Gitlab CI/CD部署方案

持续集成 (Continuous integration)是一种软件开发实践,即团队开发成员经常集成它们的工作,通过每个成员每天至少集成一次,也就意味着每天可能...

1082
来自专栏Python爬虫实战

Python环境搭建—安利Python小白的Python和Pycharm安装详细教程

人生苦短,我用Python。众所周知,Python目前越来越火,学习Python的小伙伴也越来越多。最近看到群里的小伙伴经常碰到不会安装Pyth...

682
来自专栏技术小讲堂

ASP.NET AJAX(10)__Authentication ServiceAuthentication ServiceAuthentication Service属性Authentication

在通常情况下,如果使用AJAX方式调用WebService,则可能被恶意用户利用,造成性能以及安全性的问题,所以我们需要使用一些验证方式来保护WebServic...

3589
来自专栏草根专栏

从头编写 asp.net core 2.0 web api 基础框架 (3)

Github源码地址:https://github.com/solenovex/Building-asp.net-core-2-web-api-starter-...

4137

扫码关注云+社区