.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

.NetCore3 Api使用Swagger生成api文档

 

 

 

添加并配置 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";
        });

最终效果

.NetCore3 Api使用Swagger生成api文档

上一篇:开发随笔记录——关于Swagger调试时API接口注释显示问题处理。


下一篇:Swagger:Swagger中的常用注解