原文:ASP.NET Web API Help Pages using Swagger
作者:Shayne Boyer
翻译:谢炀(kiler)
翻译:许登洋(Seay)

对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战。

在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你创建良好的文档和帮助页面。 Swashbuckle 可以通过修改 Startup.cs 作为一组 NuGet 包方便的加入项目。

  • Swashbuckle 是一个开源项目,为使用 ASP.NET Core MVC 构建的 Web APIs 生成 Swagger 文档。
  • Swagger 是一个机器可读的 RESTful API 表现层,它可以支持交互式文档、客户端 SDK 的生成和可被发现。

本教程基于 用 ASP.NET Core MVC 和 Visual Studio 创建你的第一个 Web API 文档的例子构建。如果需要对应的代码,在这里 https://github.com/aspnet/Docs/tree/master/aspnet/tutorials/first-web-api/sample 下载示例。

开始入门

Swashbuckle 有两个核心的组件

  • Swashbuckle.SwaggerGen : 提供生成描述对象、方法、返回类型等的 JSON Swagger 文档的功能。
  • Swashbuckle.SwaggerUI : 是一个嵌入式版本的 Swagger UI 工具,使用 Swagger UI 强大的富文本表现形式来可定制化的来描述 Web API 的功能,并且包含内置的公共方法测试工具。

NuGet 包

你可以通过以下方式添加 Swashbuckle:

  • 通过 Package Manager 控制台:

    Install-Package Swashbuckle -Pre
  • 在 project.json 中添加 Swashbuckle:

    "Swashbuckle": "6.0.0-beta902"
  • 在 Visual Studio 中:
    • 右击你的项目 Solution Explorer > Manage NuGet Packages
    • 在搜索框中输入 Swashbuckle
    • 点击 “Include prerelease”
    • 设置 Package source 为 nuget.org
    • 点击 Swashbuckle 包并点击 Install

在中间件中添加并配置 Swagger

在 Configure 方法里面把 SwaggerGen 添加到 services 集合,并且在 ConfigureServices 方法中,允许中间件提供和服务生成 JSON 文档以及 SwaggerUI。

  public void ConfigureServices(IServiceCollection services)
  {
      // Add framework services.
      services.AddMvc();

      services.AddLogging();

      // Add our repository type
      services.AddSingleton<ITodoRepository, TodoRepository>();

      // Inject an implementation of ISwaggerProvider with defaulted settings applied
      services.AddSwaggerGen();
  }

  // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
  public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
  {
      app.UseMvcWithDefaultRoute();

      // Enable middleware to serve generated Swagger as a JSON endpoint
      app.UseSwagger();

      // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.)
      app.UseSwaggerUi();

  }

在 Visual Studio 中, 点击 ^F5 启动应用程序并导航到 http://localhost:<random_port>/swagger/v1/swagger.json 页面可以看成生成的终端描述文档。

提示
Microsoft Edge,Google Chrome 以及 Firefox 原生支持显示 JSON 文档。 Chrome 的扩展会格式化文档使其更易于阅读。 下面的例子是简化版的。

{
"swagger": "2.0",
"info": {
    "version": "v1",
    "title": "API V1"
},
"basePath": "/",
"paths": {
    "/api/Todo": {
    "get": {
        "tags": [
        "Todo"
        ],
        "operationId": "ApiTodoGet",
        "consumes": [],
        "produces": [
        "text/plain",
        "application/json",
        "text/json"
        ],
        "responses": {
        "200": {
            "description": "OK",
            "schema": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/TodoItem"
            }
            }
        }
        },
        "deprecated": false
    },
    "post": {
        ...
    }
    },
    "/api/Todo/{id}": {
    "get": {
        ...
    },
    "put": {
        ...
    },
    "delete": {
        ...
},
"definitions": {
    "TodoItem": {
    "type": "object",
    "properties": {
        "key": {
        "type": "string"
        },
        "name": {
        "type": "string"
        },
        "isComplete": {
        "type": "boolean"
        }
    }
    }
},
"securityDefinitions": {}
}

这个文档用来驱动 Swagger UI,可以通过访问 http://localhost:<random_port>/swagger/ui 页面来查看。

所有的 ToDo controller 的方法都是可以在 UI 上面进行测试。点击方法可以展开对应的区域,输入所需的参数并且点击 “Try it out!” 。

自定义与可扩展性

Swagger 不仅是显示 API 的一个简单方法,而且有可选项:文档对象模型,以及自定义交互 UI 来满足你的视觉感受或者设计语言。

API 信息和描述

ConfigureSwaggerGen 方法用来添加文档信息。例如:作者,版权,描述。

services.ConfigureSwaggerGen(options =>
{
    options.SingleApiVersion(new Info
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = "None",
        Contact = new Contact { Name = "Shayne Boyer", Email = "", Url = "http://twitter.com/spboyer"},
        License = new License { Name = "Use under LICX", Url = "http://url.com" }
    });
});

下图展示了 Swagger UI 显示添加的版本信息。

XML 注释

为了启用 XML 注释, 在 Visual Studio 中右击项目并且选择 Properties 在 Output Settings 区域下面点击 XML Documentation file 。

另外,你也可以通过在 project.json 中设置 “xmlDoc”: true 来启用 XML 注释。

"buildOptions": {
    "emitEntryPoint": true,
    "preserveCompilationContext": true,
    "xmlDoc": true
},

配置 Swagger 使用生成的 XML 文件。

提示
对于 Linux 或者 非 Windows 操作系统,文件名和路径是大小写敏感的。 所以本例中的 ToDoApi.XML 在 Windows 上可以找到但是 CentOS 就无法找到。

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // Add framework services.
    services.AddMvc();

    services.AddLogging();

    // Add our repository type.
    services.AddSingleton<ITodoRepository, TodoRepository>();

    // Inject an implementation of ISwaggerProvider with defaulted settings applied.
    services.AddSwaggerGen();

    // Add the detail information for the API.
    services.ConfigureSwaggerGen(options =>
    {
        options.SingleApiVersion(new Info
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = "None",
            Contact = new Contact { Name = "Shayne Boyer", Email = "", Url = "http://twitter.com/spboyer"},
            License = new License { Name = "Use under LICX", Url = "http://url.com" }
        });

        //Determine base path for the application.
        var basePath = PlatformServices.Default.Application.ApplicationBasePath;

        //Set the comments path for the swagger json and ui.
        options.IncludeXmlComments(basePath + "\\TodoApi.xml");
    });
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    app.UseStaticFiles();

    app.UseMvcWithDefaultRoute();

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.)
    app.UseSwaggerUi();

}

在上面的代码中,ApplicationBasePath 获取到应用程序的根路径,是需要设置 XML 注释文件的完整路径。 TodoApi.xml 仅适用于本例,生成的XML注释文件的名称是基于你的应用程序名称。

为方法添加的三斜线注释(C# 文档注释格式)文字会作为描述显示在 Swagger UI 对应方法的头区域。

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
[HttpDelete("{id}")]
public void Delete(string id)
{
    TodoItems.Remove(id);
}

请注意,UI 是由生成的 JSON 文件驱动的,这些注释也会包含在文件中。

  "delete": {
    "tags": [
      "Todo"
    ],
    "summary": "Deletes a specific TodoItem",
    "operationId": "ApiTodoByIdDelete",
    "consumes": [],
    "produces": [],
    "parameters": [
      {
        "name": "id",
        "in": "path",
        "description": "",
        "required": true,
        "type": "string"
      }
    ],
    "responses": {
      "204": {
        "description": "No Content"
      }
    },
    "deprecated": false
  }

这是一个更强大的例子,加入 <remarks /> 那里面的内容可以是文字或添加的 JSON 或 XML 对象的方法为进一步描述方法文档而服务。

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Note that the key is a GUID and not an integer.
///
///     POST /Todo
///     {
///        "key": "0e7ad584-7788-4ab1-95a6-ca0a5b444cbb",
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>New Created Todo Item</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
[ProducesResponseType(typeof(TodoItem), 400)]
public IActionResult Create([FromBody, Required] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }
    TodoItems.Add(item);
    return CreatedAtRoute("GetTodo", new { id = item.Key }, item);
}

请注意下面是这些附加注释的在用户界面的增强效果。

DataAnnotations

你可以使用 System.ComponentModel.DataAnnotations 来标注 API controller ,帮助驱动 Swagger UI 组件。

在 TodoItem 类的 Name 属性上添加 [Required] 标注会改变 UI 中的模型架构信息。[Produces("application/json"] ,正则表达式验证器将更进一步细化生成页面传递的详细信息。代码中使用的元数据信息越多 API 帮助页面上的描述信息也会越多。

using System;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace TodoApi.Models
{
    public class TodoItem
    {
        public string Key { get; set; }
        [Required]
        public string Name { get; set; }
        [DefaultValue(false)]
        public bool IsComplete { get; set; }
    }
}

描述响应类型

API 使用开发者最关心的东西是的返回结果;具体响应类型,错误代码(如果不是标准错误码)。这些都在 XML 注释 和 DataAnnotations 中处理。

以 Create() 方法为例,目前它仅仅返回 “201 Created” 默认响应。如果数据实际创建了或者 POST 正文没有传递数据返回 “204 No Content” 错误,这是理所当然的。但是,如果没有文档知道它的存在或者存在任何其他响应,则可以通过添加下面的代码段是修复这个问题。

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Note that the key is a GUID and not an integer.
///
///     POST /Todo
///     {
///        "key": "0e7ad584-7788-4ab1-95a6-ca0a5b444cbb",
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>New Created Todo Item</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
[ProducesResponseType(typeof(TodoItem), 400)]
public IActionResult Create([FromBody, Required] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }
    TodoItems.Add(item);
    return CreatedAtRoute("GetTodo", new { id = item.Key }, item);
}

自定义 UI

stock UI 是一个非常实用的展示方案,如果你想在生成 API 文档页面的时候想把你的标题做的更好看点。

完成与 Swashbuckle 组件相关的任务很简单,但服务需要添加的资源来通常不会被包含在 Web API 项目中,所以必须建立对应的的文件夹结构来承载这些静态资源文件。

在项目中添加 "Microsoft.AspNetCore.StaticFiles": "1.0.0-*" NuGet 包。

在中间件中启用 static files 服务。

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    app.UseStaticFiles();

    app.UseMvcWithDefaultRoute();

    // Enable middleware to serve generated Swagger as a JSON endpoint
    app.UseSwagger();

    // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.)
    app.UseSwaggerUi();

}

从 Github repository 上获取 Swagger UI 页面所需的 index.html 核心文件,把他放到 wwwroot/swagger/ui 目录下,并在在同一个文件夹创建一个新的 custom.css 文件。

在 index.html 文件中引用 custom.css 。

<link href='custom.css' media='screen' rel='stylesheet' type='text/css' />

下面的 CSS 提供了一个自定义页面标题的简单的示例。

custom.css 文件

.swagger-section #header
{
    border-bottom: 1px solid #000000;
    font-style: normal;
    font-weight: 400;
    font-family: "Segoe UI Light","Segoe WP Light","Segoe UI","Segoe WP",Tahoma,Arial,sans-serif;
    background-color: black;
}

.swagger-section #header h1
{
    text-align: center;
    font-size: 20px;
    color: white;
}

index.html 正文

<body class="swagger-section">
   <div id="header">
    <h1>ToDo API Documentation</h1>
   </div>

   <div id="message-bar" class="swagger-ui-wrap" data-sw-translate>&nbsp;</div>
   <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>

你可以在这个页面有更多改进的东西,请在 Swagger UI Github repository 参阅完整的 UI 资源。

返回目录

ASP.NET Core 中文文档 第二章 指南 (09) 使用 Swagger 生成 ASP.NET Web API 在线帮助测试文档的更多相关文章

  1. ASP.NET Core中使用GraphQL - 第二章 中间件

    前文:ASP.NET Core中使用GraphQL - 第一章 Hello World 中间件 如果你熟悉ASP.NET Core的中间件,你可能会注意到之前的博客中我们已经使用了一个中间件, app ...

  2. ASP.NET Core 中文文档 第二章 指南(4.1)ASP.NET Core MVC 与 Visual Studio 入门

    原文:Getting started with ASP.NET Core MVC and Visual Studio 作者:Rick Anderson 翻译:娄宇(Lyrics) 校对:刘怡(Alex ...

  3. ASP.NET Core中使用GraphQL - 第九章 在GraphQL中处理多对多关系

    ASP.NET Core中使用GraphQL ASP.NET Core中使用GraphQL - 第一章 Hello World ASP.NET Core中使用GraphQL - 第二章 中间件 ASP ...

  4. ASP.NET Core 中文文档

    ASP.NET Core 中文文档 翻译计划 五月中旬 .NET Core RC2 如期发布,我们遂决定翻译 ASP.NET Core 文档.我们在 何镇汐先生. 悲梦先生. 张仁建先生和 雷欧纳德先 ...

  5. 关于ASP.NET Web Api的HelpPage文档注释问题

    关于ASP.NET Web Api的HelpPage文档注释问题 以前我用微软的HelpPage来自动生成的webAPI帮助文档.在使用了一段时间后发现只能显示Controller上面写的注释文档内容 ...

  6. ASP.NET Core 中文文档 第二章 指南(4.6)Controller 方法与视图

    原文:Controller methods and views 作者:Rick Anderson 翻译:谢炀(Kiler) 校对:孟帅洋(书缘) .张仁建(第二年.夏) .许登洋(Seay) .姚阿勇 ...

  7. ASP.NET Core 中文文档 第二章 指南(1)用 Visual Studio Code 在 macOS 上创建首个 ASP.NET Core 应用程序

    原文:Your First ASP.NET Core Application on a Mac Using Visual Studio Code 作者:Daniel Roth.Steve Smith ...

  8. ASP.NET Core 中文文档 第三章 原理(1)应用程序启动

    原文:Application Startup 作者:Steve Smith 翻译:刘怡(AlexLEWIS) 校对:谢炀(kiler398).许登洋(Seay) ASP.NET Core 为你的应用程 ...

  9. ASP.NET Core 中文文档 第三章 原理(6)全球化与本地化

    原文:Globalization and localization 作者:Rick Anderson.Damien Bowden.Bart Calixto.Nadeem Afana 翻译:谢炀(Kil ...

随机推荐

  1. BZOJ 2462: [BeiJing2011]矩阵模板

    2462: [BeiJing2011]矩阵模板 Time Limit: 2 Sec  Memory Limit: 128 MBSubmit: 915  Solved: 432[Submit][Stat ...

  2. .NET重载运算符

    代码如下: /// <summary> /// 坐标(结构类型) /// </summary> public struct Coordinate { public int x; ...

  3. VS2015如何新建MVC空模版项目

    直接看图吧:

  4. jsoup: Java HTML Parser (类似jquery)

    jsoup is a Java library for working with real-world HTML. It provides a very convenient API for extr ...

  5. nodejs笔记四--创建一个最简单的 express 应用

    express 是 Node.js 应用最广泛的 web 框架,利用 express 可以实现很多的web应用:首先需要需要得到一个express. 新建一个文件夹叫lesson1,进去里面安装 ex ...

  6. s3c2440 的 rtc 操作

    实时时钟(RTC)其主要功能是电源故障的制度下,使用后备电源,时钟继续.为了不浪费时间信息. s3c2440内部集成了RTC模块,并且用起来也十分简单. 其内部的寄存器BCDSEC,BCDMIN,BC ...

  7. Jquery和Javascript对象之间的转换

    jQuery 对象是通过 jQuery 包装DOM 对象后产生的对象.jQuery 对象是 jQuery 独有的,其可以使用 jQuery 里的方法,但是不能使用 DOM 的方法:例如: $(&quo ...

  8. 阿里云Centos 7.4 mssql-server

    1.阿里云服务器控制台,开启1433端口(出入方向都要开).自从微软发布linux版本后,控制台常用端口下拉列表也增加了1433. 2.如果你没配置阿里云yum源,可参照配置一下.http://www ...

  9. MYSQL 数据库导入导出命令

    在不同操作系统或MySQL版本情况下,直接拷贝文件的方法可能会有不兼容的情况发生.所以一般推荐用SQL脚本形式导入.下面分别介绍两种方法. MySQL命令行导出数据库 1,进入MySQL目录下的bin ...

  10. C# 关键字替换

    /// <summary> /// 关键字替换 /// </summary> /// <param name="body"></param ...