.NetCore3 Api使用Swagger生成api文档

Api开完成之后写文档是让人很痛苦的事儿，但文档又必须写。而且文档的格式如果没有具体要求的话，最终完成的文档则完全取决于开发者的心情。幸好有一种快速有效的方法来构建api说明文档， Swagger就是最受欢迎的REST APIs文档生成工具之一！

Swagger是最流行的API开发工具，它遵循了OpenAPI规范，可以根据API接口自动生成在线文档，这样就可以解决文档更新不及时的问题。它可以贯穿于整个API生态，比如API的设计、编写API文档等。而且Swagger还是一种通用的、与具体编程语言无关的API描述规范。

有关更多Swagger的介绍，可以参考Swagger官网，官网地址：https://swagger.io/

Swashbuckle的组成部分

• Swashbuckle.AspNetCore.Swagger：将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。
• Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。
• Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。

安装Swashbuckle

直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装

或命令行：dotnet add package Swashbuckle.AspNetCore

添加并配置 Swagger 中间件

引入命名空间：

using Swashbuckle.AspNetCore.Swagger;

在Startup.ConfigureServices 方法中，把SwaggerGen添加到服务集合中：

services.AddSwaggerGen(options =>
              {
                  // 避免出现错误: Can't use schemaId "$xxx" for type. The same schemaId is already used for type
                  options.CustomSchemaIds(type => type.FullName);

                  const string ApiVersion = "V1";
                  const string ApiName = "Xxxx";

                  options.SwaggerDoc(ApiVersion, new OpenApiInfo()
                 {
                     Version = ApiVersion,
                     Title = $"{ApiName} 接口文档"
                 });

                // 使用反射获取xml文件。并构造出文件的路径
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 启用xml注释. 该方法第二个参数启用控制器的注释，默认为false.
                options.IncludeXmlComments(xmlPath, true);
             });

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

app.UseSwagger();
             app.UseSwaggerUI(options =>
             {
　　　　　　　　　　　 options.SwaggerEndpoint($"/swagger/{Consts.ApiVersion}/swagger.json", $"{Consts.ApiName} {Consts.ApiVersion}");
　　　　　　　　　　　 // 默认访问路径：http://localhost:xxxx/swagger/index.html
 　　　　　　　　　   // 访问地址: http://localhost:xxxx/doc/index.html
　　　　　　　　　　　options.RoutePrefix = "doc";
　　　　　　　　});

最终效果