asp.net core OpenAPI规范使用(Swagger Swashbuckle SwaggerUI )

一、简介

OpenAPI 是一个与语言无关的规范，用于描述 REST API。它使计算机和用户无需直接访问源代码即可了解 REST API 的功能。其主要目标是：

尽量减少连接分离的服务所需的工作量。
减少准确记录服务所需的时间。

简而言之：

OpenAPI 是一种规范。
Swagger 是一种使用 OpenAPI 规范的工具。例如，OpenAPIGenerator Swashbuckle和SwaggerUI。

二、Swashbuckle使用

假设已经有了基于asp.net core的web api应用，具体创建过程可以参考
https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/first-web-api?view=aspnetcore-3.1&tabs=visual-studio
本文以MvcMovie为例。

1、安装Swashbuckle

右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目
在搜索框中输入“Swashbuckle.AspNetCore”
从“浏览”选项卡中选择最新的“Swashbuckle.AspNetCore”包，然后单击“安装”

2、添加并配置 Swagger 中间件

将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中：

        public void ConfigureServices(IServiceCollection services)
        {
            // Register the Swagger generator, defining 1 or more Swagger documents
            services.AddSwaggerGen();

            ......
         }

在 Startup.Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：

       public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {

            // 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.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API V1");
            });
             
            ......
         }

运行应用可以访问到说明文档和UI界面

说明文档

3、API 信息和说明
传递给 AddSwaggerGen 方法的配置操作会添加诸如作者、许可证和说明的信息：
在 Startup 类中，导入以下命名空间来使用 OpenApiInfo 类：

using Microsoft.OpenApi.Models;

    public void ConfigureServices(IServiceCollection services)
        {
            // Register the Swagger generator, defining 1 or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = "MvcMovie API",
                    Description = "A simple example ASP.NET Core Web API",
                    TermsOfService = new Uri("https://example.com/terms"),
                    Contact = new OpenApiContact
                    {
                        Name = "阿波罗",
                        Email = string.Empty,
                        Url = new Uri("https://twitter.com/zhoujyer"),
                    },
                    License = new OpenApiLicense
                    {
                        Name = "Use under LICX",
                        Url = new Uri("https://example.com/license"),
                    }
                });
            });


           ......
       }

Swagger UI 显示版本的信息为：

三、自动代码生成

1、NSwag 提供了下列功能：
能够使用 Swagger UI 和 Swagger 生成器。
灵活的代码生成功能。
借助 NSwag，无需使用现有 API。也就是说，可使用包含 Swagger 的第三方 API，并生成客户端实现。使用 NSwag，可以加快开发周期，并轻松适应 API 更改。

2、安装注册NSwag 中间件

右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目
在搜索框中输入“NSwag.AspNetCore”
从“浏览”选项卡中选择“NSwag.AspNetCore”包，然后单击“安装”

在 Startup.ConfigureServices 方法中，注册所需的 Swagger 服务

       public void ConfigureServices(IServiceCollection services)
        {
           
            // Register the Swagger services
            services.AddSwaggerDocument();

          ......
         }

在 Startup.Configure 方法中，启用中间件为生成的 Swagger 规范和 Swagger UI 提供服务

       public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {

            // Register the Swagger generator and the Swagger UI middlewares
            app.UseOpenApi();
            app.UseSwaggerUi3();
           
            ......
         }

3、下载安装NSwagStudio工具

https://github.com/RicoSuter/NSwag/wiki/NSwagStudio

4、运行NSwagStudio

在Specification URL中输入OpenAPI说明文档的URL 然后单击 Create Local Copy

在右侧窗口中选中 Typescript Client 或 CSharp Client则可以自动生成 Typescript 或 C# 使用的客户端代码，以提高开发效率。

四、参考文档

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio

https://docs.microsoft.com/zh-cn/aspnet/core/web-api/?view=aspnetcore-3.1