爱游戏全站app官网入口-爱游戏官网

mongodb从入门到实战之.net core使用mongodb开发todolist系统(2)-爱游戏全站app官网入口

2023-09-06,,

swagger是什么?

  swagger是一个规范且完整api文档管理框架,可以用于生成、描述和调用可视化的restful风格的 web 服务。swagger 的目标是对 rest api 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,swagger 消除了调用服务时可能会有的猜测。

swagger应用场景

如果你的 restful api 接口都开发完成了,你可以用 swagger-editor 来编写 api 文档( yaml 文件 或 json 文件),然后通过 swagger-ui 来渲染该文件,以非常美观的形式将你的 api 文档,展现给你的团队或者客户。
如果你的 restful api 还未开始,也可以使用 swagger ,来设计和规范你的 api,以 annotation (注解)的方式给你的源代码添加额外的数据。这样,swagger 就可以检测到这些数据,自动生成对应的 api 文档。

mongodb从到实战的相关教程

mongodb从入门到实战之mongodb简介

mongodb从入门到实战之mongodb快速入门

mongodb从入门到实战之docker快速安装mongodb

mongodb从入门到实战之mongodb工作常用操作命令

mongodb从入门到实战之.net core使用mongodb开发todolist系统(1)-后端项目框架搭建

mongodb从入门到实战之.net core使用mongodb开发todolist系统(2)-swagger框架集成

yyflight.todolist项目源码地址

github地址:https://github.com/ysgstudyhards/yyflight.todolist

swashbuckle.aspnetcore框架介绍

github源码地址:https://github.com/domaindrivendev/swashbuckle.aspnetcore

swashbuckle包含了swagger ui 的嵌入式版本,因此我们可使用中间件注册调用将该嵌入式版本托管在 asp.net core 应用中使用。

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包管理器=>程序包管理控制台

输入以下命令安装包:install-package swashbuckle.aspnetcore -version 6.2.3

添加并配置swagger中间件

1、将 swagger生成器添加到 program.cs 中的服务容器中:

// 添加swagger服务
builder.services.addswaggergen(options =>
{
//注意这里的第一个v1,v一定要是小写 否则后面swagger无法正常显示
options.swaggerdoc("v1", new openapiinfo { title = "yyflight.todolist api", version = "v1" });
});

2、在 program.cs 中,启用中间件为生成的 json 文档和 swagger ui 提供服务:

注意:要在应用的根 (https://localhost:/) 处提供 swagger ui,请将 routeprefix 属性设置为空字符串!!

// 添加swagger相关中间件
app.useswagger();
app.useswaggerui(options =>
{
options.swaggerendpoint("/swagger/v1/swagger.json", "v1");
options.routeprefix = string.empty;
});

解决[swagger]unable to resolve service for type 'microsoft.aspnetcore.mvc.apiexplorer.iapidescriptiongroupcollectionprovider' while attempting to activate

启动调试项目,报以下异常:

system.aggregateexception:“some services are not able to be constructed (error while validating the service descriptor 'servicetype: swashbuckle.aspnetcore.swagger.iswaggerprovider lifetime: transient implementationtype: swashbuckle.aspnetcore.swaggergen.swaggergenerator': unable to resolve service for type 'microsoft.aspnetcore.mvc.apiexplorer.iapidescriptiongroupcollectionprovider' while attempting to activate 'swashbuckle.aspnetcore.swaggergen.swaggergenerator'.) (error while validating the service descriptor 'servicetype: microsoft.extensions.apidescriptions.idocumentprovider lifetime: singleton implementationtype: microsoft.extensions.apidescriptions.documentprovider': unable to resolve service for type 'microsoft.aspnetcore.mvc.apiexplorer.iapidescriptiongroupcollectionprovider' while attempting to activate 'swashbuckle.aspnetcore.swaggergen.swaggergenerator'.)”

参考爱游戏官网的解决方案:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio

需要在 program.cs 中的服务容器中添加以下代码:

builder.services.addmvc();
或者
builder.services.addendpointsapiexplorer();

原因:swashbuckle 依赖于 mvc 的 microsoft.aspnetcore.mvc.apiexplorer 来发现路由和终结点。 如果项目调用 addmvc,则自动发现路由和终结点。 调用 addmvccore 时,必须显式调用 addapiexplorer 方法。 有关详细信息,请参阅 swashbuckle、apiexplorer 和路由。

修改后重新调试运行成功:

failed to load api definition解决

     //这里面的v1一定要是小写v1
services.addswaggergen(options =>
{
options.swaggerdoc("v1");
});

修改后运行正常:

swagger自定义和扩展

wagger 提供了为对象模型进行归档和自定义 ui 以匹配你的主题的选项。

api 信息和说明

传递给 addswaggergen 方法的配置操作会添加诸如作者、许可证和说明的信息。

在 program.cs 中,导入以下命名空间以使用 openapiinfo 类:

// 添加swagger服务
builder.services.addswaggergen(options =>
{
options.swaggerdoc("v1", new openapiinfo
{
title = "yyflight.todolist api",
version = "v1",
description = "mongodb从入门到实战之.net core使用mongodb开发todolist系统",
termsofservice = new uri("https://github.com/ysgstudyhards/yyflight.todolist"),
contact = new openapicontact
{
name = "example contact",
url = new uri("https://github.com/ysgstudyhards/yyflight.todolist")
},
license = new openapilicense
{
name = "example license",
url = new uri("https://github.com/ysgstudyhards/yyflight.todolist")
}
});
});

自定义swagger ui 显示版本的信息如下所示:

api swagger添加描述

在 program.cs 中注入xml相关描述:

注意:将 swagger 配置为使用按照上述说明生成的 xml 文件。 对于 linux 或非 windows 操作系统,文件名和路径区分大小写。 例如,todoapi.xml 文件在 windows 上有效,但在 centos 上无效。

// 添加swagger服务
builder.services.addswaggergen(options =>
{
options.swaggerdoc("v1", new openapiinfo
{
title = "yyflight.todolist api",
version = "v1",
description = "mongodb从入门到实战之.net core使用mongodb开发todolist系统",
termsofservice = new uri("https://github.com/ysgstudyhards/yyflight.todolist"),
contact = new openapicontact
{
name = "example contact",
url = new uri("https://github.com/ysgstudyhards/yyflight.todolist")
},
license = new openapilicense
{
name = "example license",
url = new uri("https://github.com/ysgstudyhards/yyflight.todolist")
}
}); // 获取xml文件名
var xmlfile = $"{assembly.getexecutingassembly().getname().name}.xml";
// 获取xml文件路径
var xmlpath = path.combine(appcontext.basedirectory, xmlfile);
// 添加控制器层注释,true表示显示控制器注释
options.includexmlcomments(xmlpath, true);
});

项目右键,选择属性,找到生成下面的输出选中生成包含api文档的文件,如下图所示:

注意:关于xml文档文件路径是需要你先勾选上面生成包含api文档的文件的时候运行项目才会生成该项目的xml文档,然后可以把生成的xml文档放到你想要放到的位置。

为什么要这样设置呢,如果不设置的话,发布时候会出问题,找不到 xml文件!!

关于swagger json paths为空问题解决

引入swagger相关中间件和注入相关服务,运行项目依旧不显示接口,原因是还需要注入controllers服务,添加如下代码:

builder.services.addcontrollers();

最终program.cs完整的示例代码和运行效果

using microsoft.openapi.models;
using system.reflection; var builder = webapplication.createbuilder(args); // add services to the container. //builder.services.addmvc();
builder.services.addcontrollers();
builder.services.addendpointsapiexplorer(); // 添加swagger服务
builder.services.addswaggergen(options =>
{
options.swaggerdoc("v1", new openapiinfo
{
title = "todolist api",
version = "v1",
description = ".net7使用mongodb开发todolist系统",
contact = new openapicontact
{
name = "github源码地址",
url = new uri("https://github.com/ysgstudyhards/yyflight.todolist")
}
}); // 获取xml文件名
var xmlfile = $"{assembly.getexecutingassembly().getname().name}.xml";
// 获取xml文件路径
var xmlpath = path.combine(appcontext.basedirectory, xmlfile);
// 添加控制器层注释,true表示显示控制器注释
options.includexmlcomments(xmlpath, true);
// 对action的名称进行排序,如果有多个,就可以看见效果了
options.orderactionsby(o => o.relativepath);
}); var app = builder.build(); // configure the http request pipeline.
if (app.environment.isdevelopment())
{
app.usedeveloperexceptionpage();
} //使中间件能够将生成的swagger用作json端点.
//app.useswagger();
app.useswagger(c => { c.routetemplate = "swagger/{documentname}/swagger.json"; });
//允许中间件为swagger ui(html、js、css等)提供服务,指定swagger json端点.
app.useswaggerui(options =>
{
options.swaggerendpoint("/swagger/v1/swagger.json", "my api v1");
options.routeprefix = string.empty;
}); app.usehttpsredirection(); app.mapcontrollers(); app.run();

参考文章

https://learn.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-7.0&tabs=visual-studio

mongodb从入门到实战之.net core使用mongodb开发todolist系统(2)-swagger框架集成的相关教程结束。

网站地图