.NetCore3 Api使用Swagger生成api文档

2024-01-05 12:40:58

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";
　　　　　　　　});

最终效果

码农公寓

添加并配置 Swagger 中间件

相关文章