标签：API Swagger AspNetCore api 文档 Swashbuckle Api NetCore3 options
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";
});
最终效果
标签：API,Swagger,AspNetCore,api,文档,Swashbuckle,Api,NetCore3,options 来源： https://www.cnblogs.com/superfeeling/p/15253502.html
本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享； 2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关； 3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关； 4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除； 5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。