其他分享
首页 > 其他分享> > .NetCore3 Api使用Swagger生成api文档

.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

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

最终效果

标签:API,Swagger,AspNetCore,api,文档,Swashbuckle,Api,NetCore3,options
来源: https://www.cnblogs.com/superfeeling/p/15253502.html