.net web api中Swagger使用教程_dotnetweb 项目集成swagger
文章目录
-
- 1.概要
- 2.相关知识
-
- OpenAPI【也叫OAS】（规范）
- Swagger（工具集）
- Swashbuckle（.NET实现）
- 三者的关系
- 3.使用流程
1.概要
swagger使用教程，以.net 8为例
2.相关知识
Swagger、Swashbuckle、open api 这个三个术语在使用中经常一起出现，所以先了解下这个3个东西是什么：
OpenAPI【也叫OAS】（规范）
是什么：OpenAPI是一个行业标准的规范（最初称为Swagger规范），用于描述RESTful API的结构。
作用：定义了一种机器可读的格式（通常用YAML或JSON编写）来描述API的路径、参数、请求/响应格式、认证方式等
例如：描述GET /api/products需要什么参数，返回什么数据结构
特点：与语言无关，任何技术栈都可以实现
关键点：OpenAPI是\"规范/标准\"，就像HTTP协议一样，它只定义规则，不涉及具体实现。
Swagger（工具集）
是什么：Swagger是一套围绕OpenAPI规范的工具生态系统。
关键点：Swagger是\"工具\"，用于实现和展示OpenAPI规范。
历史：
最初Swagger既是规范也是工具
2015年规范部分捐赠给Linux基金会后改名为OpenAPI
工具部分保留Swagger名称
包含的主要工具：
- Swagger UI：可视化API文档的交互式网页（就是你在浏览器看到的那个页面）
- Swagger Editor：基于浏览器的OpenAPI规范编辑器
- Swagger Codegen：根据API描述生成客户端SDK或服务端存根代码
Swashbuckle（.NET实现）
是什么：一个.NET库，用于自动生成OpenAPI文档并与Swagger UI集成。
作用：
扫描你的ASP.NET Core/Web API项目
根据控制器、路由、模型等自动生成OpenAPI规范的JSON文件
嵌入Swagger UI到你的应用中，提供可视化界面
组成：
Swashbuckle.AspNetCore.Swagger：核心功能，生成OpenAPI文档
Swashbuckle.AspNetCore.SwaggerGen：从代码生成OpenAPI规范
Swashbuckle.AspNetCore.SwaggerUI：提供交互式UI
关键点：Swashbuckle是\".NET的实现\"，把前两者带入.NET世界。
三者的关系
OpenAPI 是规范，定义了 API 描述的标准格式。
Swagger 是 OpenAPI 规范的工具集，提供 UI、编辑器等实现。
Swashbuckle 是 .NET 平台上的 OpenAPI/Swagger 实现，将 OpenAPI 规范集成到 ASP.NET Core 应用中。
3.使用流程
- 创建.net项目
- 引入swagger包
- 基础配置
- 配置token验证
基础配置：
在 Program.cs 中添加 Swagger 服务：
using Microsoft.OpenApi.Models;namespace JWTAuthDemo{ public class Program { public static void Main(string[] args) { var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); //根据配置生成openapi规范文件 builder.Services.AddSwaggerGen(c => { //下面这个v1代表的是版本，会根据这个名字作为openapi规范文件的路径之一，下面配置swaggerui的访问url时，要用到这个版本名字 c.SwaggerDoc(\"v1\", new OpenApiInfo() { Description = \"swagger的描述\", Version = \"版本\",//这里的版本就是展示用的 Contact=new OpenApiContact() { Name=\"联系人姓名\", Email=\"邮箱\", }, Title=\"swagger标题\" }); }); var app = builder.Build(); if (app.Environment.IsDevelopment()) { app.UseSwagger(); //暴露 OpenAPI 规范 为可访问的 HTTP 端点（如 /swagger/v1/swagger.json）。 //告诉应用在访问 Swagger UI 时，从哪个 URL 获取 OpenAPI 规范文件（即 swagger.json） app.UseSwaggerUI(c => { c.SwaggerEndpoint(\"/swagger/v1/swagger.json\", \"Swagger Demo API v1\"); }); } app.UseAuthorization(); app.MapControllers(); app.Run(); } }}配置token验证，写上以下代码，swagger请求时就会在请求头加上token
```csharp // 添加安全定义 c.AddSecurityDefinition(\"Bearer\", new OpenApiSecurityScheme { Description = \"请输入token\", Name = \"Authorization\", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey, Scheme = \"Bearer\" }); c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = \"Bearer\" } }, Array.Empty<string>() } });
