asp.net core系列 37 WebAPI 使用OpenAPI (swagger)中间件

一.概述

　　在使用web api时，对于开发人员来说，了解其各种方法可能是一项挑战。在asp.net core上，web api 辅助工具介绍二个中间件，包括：swashbuckle和nswag .net。本篇先讲swashbuckle。二者都使用swagger规范，swagger也称为openapi，解决了为web api生成有用文档和帮助页面的问题。它提供了诸如交互式文档，客户端sdk生成和api可发现性等好处。

　　(1) swashbuckle.aspnetcore是一个开源项目，用于为asp.net core web api生成swagger文档。

　　(2) nswag是另一个开源项目，该项目将swashbuckle和autorest（客户端生成）的功能集成在一个工具链中。用于生成swagger文档并将swagger ui或redoc集成到asp.net core web api中。此外，nswag还提供了为api生成c＃和typescript客户端代码的方法。

　　

　　1.1 什么是swagger / openapi

　　　　swagger是一种与开发语言无关的规范，用于描述rest api。swagger项目被捐赠给openapi计划，现在称为openapi。两个名称可互换使用; 但是，openapi是首选。它允许计算机和it人理解服务的功能，而无需直接访问实现（源代码，网络访问，文档）。一个目标是最小化连接不相关服务所需的工作量。另一个目标是减少准确记录服务所需的时间。

 

　　1.2  swagger规范（swagger.json）

　　　　swagger流程的核心是swagger规范，默认情况下是一个名为swagger.json的文档。它由swagger工具链（或其第三方实现）根据你的服务生成。它描述了 api 的功能以及使用 http 对其进行访问的方式。 它驱动 swagger ui，并由工具链用来启用发现和客户端代码生成。

 

　　1.3 swagger ui

　　　　swagger ui 提供了基于 web 的 ui，它使用生成的 swagger 规范提供有关服务的信息。 swashbuckle 和 nswag 均包含 swagger ui 的嵌入式版本，因此可使用中间件注册调用将该嵌入式版本托管在 asp.net core 应用中。

 

二.  添加 swashbuckle中间件

　　关于swashbuckle有三个主要组成部分：

　　(1) swashbuckle.aspnetcore.swagger： 一个swagger对象模型和中间件，用于将swaggerdocument对象公开为json端点。

　　(2) swashbuckle.aspnetcore.swaggergen：一个swagger生成器，可swaggerdocument直接从路由，控制器和模型构建对象。它通常与swagger端点中间件结合使用，以自动显示swagger json。

　　(3) swashbuckle.aspnetcore.swaggerui： swagger ui工具的嵌入式版本。它解释 swagger json 以构建描述 web api 功能的可自定义的丰富体验。它包括用于公共方法的内置测试工具。

　　

　　 2.1 包安装

　　　　通过vs 2017的程序包管理器控制台，运行安装install-package swashbuckle.aspnetcore -version 5.0.0-beta。 安装信息如下所示：

 

　　2.2  配置swagger中间件

　　　　将 swagger 生成器添加到 startup.configureservices 方法中的服务集合中

            //将swaggergen服务添加到服务集合中， openapiinfo是它的自带类。
            services.addswaggergen(c =>
            {
                //注意不能用大写v1，不然老报错，not found /swagger/v1/swagger.json
                c.swaggerdoc("v1", new openapiinfo { title = "my api", version = "v1" });
            });

　　　　startup.configure 方法中，启用中间件为生成的 json 文档和 swagger ui 提供服务

public void configure(iapplicationbuilder app)
{
    //...
     
    // enable middleware to serve generated swagger as a json endpoint.
    app.useswagger();

    // enable middleware to serve swagger-ui (html, js, css, etc.), 
    // specifying the swagger json endpoint.
    // useswaggerui方法调用启用静态文件中间件。
    app.useswaggerui(c=> {
                c.swaggerendpoint("/swagger/v1/swagger.json", "my api v1");
            });

    app.usemvc();
}

 　　　　启动应用，并导航到 http://localhost:<port>/swagger/index.html下，查看web api生成swagger文档如下所示(一个网页，二处截图拼在一起)：

 

三.自定义和扩展

　　swagger 提供了为对象模型进行归档和自定义 ui 以匹配你的主题的选项。

　　

　　3.1 api 信息和说明的配置

　　　　可以在addswaggergen方法中配置，添加诸如作者，许可证和描述之类的信息，通过openapiinfo类来添加。

            services.addswaggergen(c =>
            {
                //注意不能用大写v1，不然老报错，not found /swagger/v1/swagger.json
                c.swaggerdoc("v1", new openapiinfo{
                    version = "v1",
                    title = "todo api",
                    //服务描述
                    description = "a simple example asp.net core web api",
                    //api服务条款的url
                    termsofservice = new uri("http://tempuri.org/terms"),
                    contact = new openapicontact
                    {
                        name = "joe developer",
                        email = "[e-mail]"
                    },
                    license = new openapilicense
                    {
                        name = "apache 2.0",
                        url = new uri("http://www.apache.org/licenses/license-2.0.html")
                    }
                });
            });

　　　　swagger ui 显示版本的信息：

 

　　3.2 xml注释api

　　　　在“解决方案资源管理器”中右键单击该项目，然后选择“编辑 <project_name>.csproj”。 手动添加以下代码到 .csproj 文件中。

    <propertygroup>
      <generatedocumentationfile>true</generatedocumentationfile>
      <nowarn>$(nowarn);1591</nowarn>
    </propertygroup>

　　　　接下来配置 swagger 以使用生成的 xml 文件。对于 linux 操作系统，文件名和路径区分大小写。例如，“todoapi.xml”文件在 windows 上有效，但在 centos 上无效。配置和解决如下所示：

    services.addswaggergen(c =>
    {
        //...配置swaggerdoc 省略
        // set the comments path for the swagger json and ui.
        var xmlfile = $"{assembly.getexecutingassembly().getname().name}.xml";
        var xmlpath = path.combine(appcontext.basedirectory, xmlfile);
        c.includexmlcomments(xmlpath);
    });

　　　　接着对每个api方法添加操作说明注释，以删除api来描述如下所示：

        /// <summary>
        /// 删除一个todoitem
        /// </summary>
        /// <remarks>
        ///  sample request:
        ///  delete: api/todo/2
        /// </remarks>
        /// <param name="id"></param>
        /// <returns>不返回内容</returns>
        /// <response code="204">删除成功，不返回内容</response>
        /// <response code="404">删除失败，未找到该记录</response>
        [httpdelete("{id}", name = "deletetodoitem")]
        [producesresponsetype(204)]
        [producesresponsetype(404)]
        public async task<iactionresult> deletetodoitem(long id)
        {
            var todoitem = await _context.todoitems.findasync(id);
            if (todoitem == null)
            {
                return notfound();
            }

            _context.todoitems.remove(todoitem);
            await _context.savechangesasync();

            return nocontent();
        }

　　　　启动程序后，swagger ui 显示的delete删除api的描述如下图。还可以点击try it out按钮进行测试删除，图中显示server response 返回204删除成功。

　　

　　3.2 数据注释

　　　　使用 system.componentmodel.dataannotations 命名空间中的属性来修饰模型，以帮助驱动 swagger ui 组件。下面将 [required] 属性添加到 todoitem 类的 name 属性：

         [required]
        public string name { get; set; }

　　　　此属性的状态更改 ui 行为并更改基础 json 架构：

　　　　　　

　　　　将 [produces("application/json")] 属性添加到 api 控制器。 这样做的目的是声明控制器的操作支持 application/json 的响应内容类型：

[produces("application/json")]
[route("api/[controller]")]
[apicontroller]
public class todocontroller : controllerbase
{
   //..
}

 　　　　　　

　　

　　　　最后还可以自定义swagger ui，这里不在演示，可以查看官网。更多功能介绍上github。

 

　　参考文献：

　　　　swashbuckle 和 asp.net core 入门

　　　　github