本文还有配套的精品资源，点击获取 menu-r.4af5f7ec.gif

简介：本文介绍如何在使用.NET Core MVC框架构建的Web服务中集成Swagger API工具，并实现令牌身份验证。Swagger允许开发者交互、测试和文档化API，而令牌身份验证通过OAuth 2.0或JWT保证API安全性。内容包括.NET Core MVC Web服务概念、Swagger集成、令牌身份验证原理和配置，以及如何使用Swagger UI测试和文档化API。文章还包括示例代码，展示如何在项目中配置Swagger服务和JWT认证服务。
在具有令牌身份验证的.NET Core MVC Web服务中使用Swagger

1. .NET Core MVC Web服务概念

.NET Core MVC Web服务是构建现代化、可扩展的Web应用程序的基础。它结合了MVC（模型-视图-控制器）设计模式的高效性，以及ASP.NET Core的轻量级和跨平台特性。本章将详细介绍.NET Core MVC的核心概念，包括其架构、控制器、动作方法以及如何处理HTTP请求和响应。

1.1 .NET Core MVC架构概述

.NET Core MVC 架构遵循经典的MVC设计模式，其中：
- 模型(Model) : 代表应用程序的数据结构，通常包含数据访问逻辑。
- 视图(View) : 用于显示模型数据。它负责生成客户端的HTML输出。
- 控制器(Controller) : 处理用户输入和请求，调用模型层的业务逻辑，并选择视图进行数据渲染。

1.2 控制器和动作方法

在.NET Core MVC中， 控制器 是处理HTTP请求的主要部分。每个控制器由一系列的 动作方法 组成，这些动作方法对应不同的HTTP请求，如GET、POST等。

public class HomeController : Controller
{
    public IActionResult Index()
    {
        return View();
    }

    [HttpPost]
    public IActionResult Create(string name)
    {
        // 处理创建逻辑
        return RedirectToAction("Index");
    }
}

1.3 处理HTTP请求和响应

.NET Core MVC通过使用 IActionResult 接口处理HTTP响应。动作方法返回类型为 IActionResult 接口的实例，该实例描述了如何构建响应。例如， View() 方法返回一个视图，而 RedirectToAction() 方法则重定向到另一个动作。

通过理解这些基础知识，我们可以构建出结构清晰、功能强大的Web服务，为后续的Swagger集成打下坚实的基础。

2. Swagger集成与OpenAPI Specification

2.1 Swagger在.NET Core中的集成方式

2.1.1 介绍Swagger工具和其生态系统

Swagger是一种流行的API开发工具，它提供了一种简洁的方式来定义、构建、记录和使用RESTful Web服务。Swagger工具集包括了Swagger Editor用于定义API、Swagger UI用于生成交互式的API文档，以及Swagger Codegen用于生成服务端和客户端代码。Swagger简化了API的文档工作，并且使得API能够被机器和人阅读。通过Swagger，开发者和API消费者可以更轻松地理解API的结构和功能，从而提高开发效率和用户体验。

2.1.2 在.NET Core项目中添加Swagger支持

要将Swagger集成到.NET Core项目中，首先需要安装 Swashbuckle.AspNetCore NuGet包。这个包是Swagger工具的.NET Core实现，它会帮助我们自动生成API文档并集成Swagger UI。通过以下命令安装：

dotnet add package Swashbuckle.AspNetCore --version 5.6.3

然后，需要在项目的启动配置文件 Startup.cs 中配置Swagger。具体操作如下：

public void ConfigureServices(IServiceCollection services)
{
    // 配置Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 配置Swagger UI
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    // 其他配置...
}

上述代码在 ConfigureServices 方法中设置了Swagger文档的基本信息，并在 Configure 方法中启用了Swagger和Swagger UI，这样就可以通过访问 /swagger 路径来查看生成的API文档和交互式的测试界面了。

2.1.3 配置Swagger以扫描和记录API

Swagger的自动文档生成功能需要扫描程序集中的API控制器来收集信息。我们可以通过配置来精细控制Swagger的行为，比如忽略特定的控制器、操作或者模型属性。下面展示了如何定制化Swagger的扫描过程：

// 在Startup.cs的ConfigureServices方法中配置
public void ConfigureServices(IServiceCollection services)
{
    // ...

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

        // 添加API安全定义
        c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
        {
            Description = "OAuth2授权码模式。",
            Type = SecuritySchemeType.OAuth2,
            Flows = new OpenApiOAuthFlows
            {
                AuthorizationCode = new OpenApiOAuthFlow
                {
                    AuthorizationUrl = new Uri("https://example.com/oauth/authorize"),
                    TokenUrl = new Uri("https://example.com/oauth/token"),
                    Scopes = new Dictionary<string, string>
                    {
                        { "openid", "OpenID scope" }
                    }
                }
            }
        });

        // 添加安全要求
        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
                },
                new[] { "openid" }
            }
        });
    });

    // ...
}

这段代码配置了Swagger，以便它可以在文档中使用OAuth 2.0认证。此外，通过 c.OperationFilter<AssignOAuth2SecurityRequirements>() 可以添加安全需求，确保API文档显示正确的安全标志。

2.2 OpenAPI Specification的理解与应用

2.2.1 OpenAPI Specification的基本结构

OpenAPI Specification（OAS）定义了一种用于描述API的标准化方式，它基于YAML或JSON格式。OAS的结构包含了API的基本信息，比如服务的路径、操作、参数、模型以及认证方式等。OAS文档通常分为以下几个部分：

  • Info : 包含API的基本描述信息，如名称、版本、描述和联系信息等。
  • Paths : API路径（路由）与对应的操作（GET、POST等）的列表。
  • Definitions : 定义数据模型的结构，它们用在请求和响应体中。
  • Security Definitions : 描述API使用的认证机制。
  • Parameters : 定义用于操作的参数。
  • Responses : 定义API可能返回的消息和状态码。
2.2.2 使用OpenAPI生成API文档

Swagger的生成器功能允许开发者基于OAS规范生成交互式的API文档。在.NET Core项目中集成Swashbuckle.AspNetCore后，通过 UseSwagger 和 UseSwaggerUI 中间件，能够自动地从项目中的API定义生成和展示OAS文档。

// 在Startup.cs的Configure方法中配置
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...

    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.InjectJavascript("/swagger-ui/custom.js"); // 可以添加自定义的JavaScript来扩展Swagger UI的功能
    });

    // ...
}

通过访问 /swagger/v1/swagger.json ，可以获取JSON格式的OAS文档。 /swagger 路径下还会展示Swagger UI界面，它提供了与API交互的前端界面。

2.2.3 文档版本管理和文档变更跟踪

版本管理是API文档维护过程中的一个重要方面。OpenAPI Specification通过在文档的不同部分定义不同的版本来支持版本化。开发者可以在路径、操作和模型定义中指定版本信息。这有助于保持文档的一致性，并确保API的使用者能够找到他们需要的信息。

openapi: 3.0.3
info:
  version: "1.0.0"
  title: "My API"
paths:
  /api/v1/users:
    get:
      ...
  /api/v2/users:
    get:
      ...

在上例中， /api/v1/users 和 /api/v2/users 表示两个不同版本的用户API路径。文档变更跟踪通常由版本控制系统完成，比如Git，它能够记录和管理文档的每一次修改。

表格和代码块只是章节内容的一部分。请确保所有提及的Markdown元素都得到适当的展示，并且所有的代码块都有逻辑分析和参数说明。

为了完整地遵循Markdown格式和要求，以下部分将详细展示 Swagger集成与OpenAPI Specification 章节的剩余内容，这包括表格、mermaid流程图、和代码块等。

2.2 OpenAPI Specification的理解与应用（续）

2.2.3 文档版本管理和文档变更跟踪（续）

为了更好的展示如何使用表格来展示API版本信息，以下是一个简化的表格示例，它可以用来说明在不同版本中API的变化。

API端点 版本 1.0.0 版本 2.0.0 备注
/users GET、POST GET、PUT 版本2.0.0中移除了POST，增加了PUT操作
/orders GET GET、POST 版本2.0.0新增了POST操作，用于创建订单

表格中的每一列代表一个API版本，每一行代表一个不同的API端点及其支持的操作。这种视觉化的比较方式可以帮助API的使用者快速理解API版本之间的差异。

2.2.1 OpenAPI Specification的基本结构（续）

为了深入理解OAS的基本结构，接下来通过一个mermaid流程图来表示一个典型的OAS文档的结构。

graph TD
    Info[Info]
    Paths[Paths]
    Definitions[Definitions]
    Security[Security Definitions]
    Parameters[Parameters]
    Responses[Responses]

    Info --> Paths
    Paths --> Definitions
    Definitions --> Security
    Paths --> Parameters
    Paths --> Responses

mermaid流程图展示了OAS文档的不同部分之间的关系。信息部分提供了API的基本概览，而路径部分则是API的核心，通常链接到定义、安全要求、参数和响应部分。

代码块和逻辑分析

接下来，展示一个使用.NET Core创建API端点的代码示例，并且说明如何在Swagger中描述该操作。

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<WeatherForecast>> Get()
    {
        // 模拟获取数据
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

上述代码定义了一个简单的GET端点 /weatherforecast ，用于返回模拟的天气预报数据。为了在Swagger UI中描述这个操作，我们需要在方法上添加Swagger属性来提供额外的信息。

/// <summary>
/// 获取天气预报。
/// </summary>
/// <returns>返回天气预报列表。</returns>
[HttpGet]
[SwaggerOperation(Summary = "获取天气预报", Description = "返回一个包含5天天气预报的列表。")]
public ActionResult<IEnumerable<WeatherForecast>> Get()
{
    // 同上
}

在这里， [SwaggerOperation] 属性用于设置Swagger UI中显示的摘要和描述信息，使得API的使用者可以更清晰地理解每个API端点的功能和用途。

以上展示了Swagger集成与OpenAPI Specification的详细内容，从基础的集成方式到OpenAPI规范的深入理解和应用。通过代码、流程图、表格等Markdown元素的运用，文章内容的连贯性和可读性得到了进一步提升。

3. 令牌身份验证基础（OAuth 2.0和JWT）

3.1 OAuth 2.0和JWT简介

3.1.1 OAuth 2.0协议的基本原理

OAuth 2.0是目前广泛使用的授权框架，它允许用户授予第三方应用有限的访问权限，而无需共享自己的用户名和密码。这种授权机制通常通过访问令牌（Access Tokens）来实现，这些令牌代表了特定的权限范围和有效性期限。OAuth 2.0框架的核心在于四种授权流程：授权码（Authorization Code）、简化流程（Implicit）、密码凭证（Resource Owner Password Credentials）和客户端凭证（Client Credentials）。

认证授权机制

在OAuth 2.0中，”认证”指的是用户的身份识别过程，而”授权”则是用户授权第三方应用访问其资源的过程。在标准的授权流程中，用户首先访问应用，应用向授权服务器发送请求并引导用户进行身份验证，一旦用户完成验证，授权服务器会提供授权码，应用随后用该授权码交换访问令牌。

安全性和授权服务器

安全是OAuth 2.0的重要组成部分，而授权服务器负责生成和管理访问令牌。这个令牌必须在客户端和服务端之间安全传输，并且需要由服务端验证其有效性。

3.1.2 JSON Web Tokens (JWT)的结构和优势

JWT是一种轻量级的、紧凑型的、自包含的格式，用于在各方之间安全地传输信息。它由三部分组成： Header（头部）、Payload（载荷）和 Signature（签名）。头部通常包含令牌的类型（即JWT）和所使用的签名算法。载荷中包含了令牌的声明（Claims），这些声明是关于实体（通常是用户）的陈述，可以包含多个键值对，用于描述用户或其他实体。签名则是通过头部和载荷使用特定算法生成的。

JWT的优势

JWT的结构和特性使其成为Web应用中理想的身份验证和信息交换手段。其优势主要包括：

  • 可读性 ：由于JWT是Base64编码的JSON对象，因此它是可读的。
  • 紧凑性 ：JWT可以发送到客户端，无需在服务器端进行存储。
  • 安全性 ：可以通过数字签名确保JWT的真实性和完整性。

此外，由于JWT不依赖于Cookie，它可以轻松地在HTTP请求中传输，并且可以用于跨域认证。这些特点使得JWT成为构建分布式系统和微服务架构中实现认证和授权的理想选择。

3.2 实现令牌身份验证机制

3.2.1 认证服务器与资源服务器的概念

在OAuth 2.0框架中，认证服务器主要负责处理认证流程和发放令牌。它是整个授权流程的核心，负责验证用户身份，处理客户端请求，以及颁发访问令牌和刷新令牌。而资源服务器则是托管受保护资源的服务器，它接收来自客户端的访问令牌，并验证令牌的有效性，然后提供相应的资源访问。

3.2.2 创建和验证JWT令牌

创建JWT令牌通常涉及以下步骤：

  1. 定义需要包含在JWT中的声明，如用户ID、过期时间等。
  2. 根据定义的声明构建Payload。
  3. 选择合适的签名算法，如HS256、RS256等，并生成Header。
  4. 使用Header和Payload以及密钥生成JWT签名。
  5. 将 Header、Payload 和 Signature 组合起来，形成最终的JWT令牌。
// C# 代码示例：创建JWT令牌
var claims = new[] {
    new Claim(JwtRegisteredClaimNames.Sub, "user@example.com"),
    new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
    // 其他自定义声明
};

var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("SecretKey"));
var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

var token = new JwtSecurityToken(
    issuer: "https://example.com",
    audience: "https://example.com",
    claims: claims,
    expires: DateTime.Now.AddMinutes(30),
    signingCredentials: credentials
);

string tokenString = new JwtSecurityTokenHandler().WriteToken(token);

上述代码块首先定义了JWT中需要包含的声明，然后创建了一个密钥，并使用HMAC SHA256算法生成签名。最后，创建了一个 JwtSecurityToken 对象，并将其转换为字符串形式的JWT令牌。

验证JWT令牌一般通过解析令牌并检查签名来完成。如果签名验证失败，说明令牌可能被篡改或者过期。

3.2.3 授权码、刷新令牌和访问令牌的生命周期

在OAuth 2.0中，授权码、刷新令牌和访问令牌有各自的生命周期和用途：

  • 授权码（Authorization Code） ：由授权服务器生成，并在用户完成身份验证后提供给客户端，客户端随后用它来交换访问令牌。
  • 访问令牌（Access Token） ：客户端用于访问资源服务器的资源，通常有一定的有效期限。
  • 刷新令牌（Refresh Token） ：用于在访问令牌过期后获取新的访问令牌。

通常情况下，访问令牌是短期有效的，目的是为了减少访问令牌被滥用的风险。一旦访问令牌过期，客户端可以使用刷新令牌来获取新的访问令牌，从而继续访问受保护的资源，直到刷新令牌本身也被消耗或过期。这种机制保证了授权流程的安全性和资源访问的可控性。

4. 配置Swagger以支持令牌验证

4.1 配置Swagger支持OAuth 2.0

4.1.1 在Swagger中添加OAuth 2.0认证流程

要在Swagger中添加OAuth 2.0认证流程，首先需要在项目中安装Swagger相关的NuGet包，如 Swashbuckle.AspNetCore 和 Swashbuckle.AspNetCore.Annotations 。然后，可以使用 AddSwaggerGen 方法配置OAuth 2.0支持。以下代码块展示了如何在.NET Core应用的Startup.cs文件中配置Swagger，以支持OAuth 2.0认证流程。

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.OAuth2,
            Flows = new OpenApiOAuthFlows
            {
                Implicit = new OpenApiOAuthFlow
                {
                    AuthorizationUrl = new Uri("https://your-auth-server.com/oauth/authorize"),
                    Scopes = new Dictionary<string, string>
                    {
                        {"read", "Access read operations"},
                        {"write", "Access write operations"}
                    }
                }
            }
        });
        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
                },
                new[] { "read", "write" }
            }
        });
    });

    // Other service configurations...
}

在这段代码中， AddSecurityDefinition 方法用于定义OAuth 2.0的认证方式，其中包括授权URL和作用域（Scopes）。 AddSecurityRequirement 方法则是用来指定需要进行OAuth 2.0认证的API路径。

4.1.2 配置Swagger UI以支持令牌获取

配置Swagger UI以支持令牌获取，用户在使用UI测试API时可以方便地获取和刷新令牌。以下是一个配置Swagger UI以支持OAuth 2.0的示例：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // Other configurations...

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.OAuthClientId("your-client-id");
        c.OAuthAppName("My API - Swagger");
        c.OAuthUsePkce();
    });

    // Other configurations...
}

在这个配置中， OAuthClientId 和 OAuthAppName 分别用于提供OAuth 2.0客户端ID和应用名称。 OAuthUsePkce 是用于启用PKCE (Proof Key for Code Exchange)，这是为了增强OAuth 2.0流的安全性。

4.2 实现Swagger安全模式

4.2.1 使用Swagger安全定义配置

要实现Swagger的安全定义配置，可以利用OpenAPI规范中的 securityDefinitions 对象来定义安全要求。这在之前的配置Swagger以支持OAuth 2.0中已经涉及，这里将进一步解释安全定义的作用。

安全定义可以指定API请求需要哪些类型的安全措施。在上面的配置示例中， securityDefinitions 定义了一个名为 oauth2 的安全方案，指明了授权服务器的URL、作用域和令牌的获取方式。当这个安全方案被定义后，Swagger UI会展示一个登录框，用户可以通过它获取令牌，之后该令牌会被用在API请求中。

4.2.2 集成JWT令牌验证到Swagger安全模式

要集成JWT令牌验证到Swagger安全模式，需要在API层面实现JWT的验证逻辑。这通常涉及到中间件和控制器动作方法的更新。以下是一个使用JWT令牌验证的示例：

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = Configuration["Jwt:Issuer"],
                ValidAudience = Configuration["Jwt:Audience"],
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["Jwt:Key"]))
            };
        });

    // Other service configurations...
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseAuthentication();
    app.UseAuthorization();

    // Other configurations...
}

这段代码首先配置了认证服务，设置了JWT的验证参数，指明了令牌的有效发行者、观众和签名密钥。之后在 Configure 方法中调用了 UseAuthentication 和 UseAuthorization 中间件来应用这些设置。

4.2.3 测试Swagger的令牌验证功能

测试Swagger的令牌验证功能，可以使用Swagger UI的授权按钮来获取令牌，并在API请求中使用该令牌。用户可以在Swagger UI中点击“Authorize”按钮，输入必要的凭证信息，获取到JWT令牌后，该令牌会自动附加到后续API请求的头部中。

为了测试这个流程，可以手动在Swagger UI中输入API请求，并观察请求头部是否包含了正确的 Authorization 字段。如果一切配置正确，应该能够成功地调用需要认证的API端点。

sequenceDiagram
    participant User
    participant SwaggerUI
    participant AuthServer
    participant API

    User->>SwaggerUI: Click on Authorize button
    SwaggerUI->>AuthServer: Send credentials for token
    AuthServer-->>SwaggerUI: Respond with JWT token
    User->>SwaggerUI: Make an API request with token
    SwaggerUI->>API: Forward the request with Authorization header
    API-->>SwaggerUI: Respond to the request

以上流程图简要描述了用户通过Swagger UI获取JWT令牌，并使用该令牌调用API的过程。确保Swagger UI和API服务器之间的交互能够正常工作，是验证整个认证流程的关键步骤。

5. 使用Swagger UI进行API测试和文档化

5.1 Swagger UI的基本操作

5.1.1 探索Swagger UI的用户界面

Swagger UI 是一个直观的用户界面，旨在让开发者和API消费者能够轻松地探索和测试API。用户界面（UI）通常被分为几个主要部分：API文档导航栏、请求参数区域、请求方法选择下拉菜单、API请求区域、响应区域。

API文档导航栏
  • 提供API端点的快速导航。
  • 允许用户通过点击不同的API端点名称，跳转到特定的API接口描述。
请求参数区域
  • 在此区域，可以设置API请求所需的参数，比如查询参数、路径参数或者请求体。
  • 参数通常可以是静态的，也可以是动态的（例如使用Swagger UI内置的Try it out功能）。
请求方法选择下拉菜单
  • 提供不同的HTTP方法，如GET、POST、PUT、DELETE等供用户选择。
  • 改变请求方法后，Swagger UI会更新请求示例以匹配所选方法。
API请求区域
  • 展示了实际的API请求URL。
  • 包括了请求所需的全部信息，如请求头、查询参数和路径参数。
响应区域
  • 显示API请求的响应内容。
  • 支持多种格式的响应体查看，例如JSON、XML等。
  • 包含响应代码和响应时间信息。

5.1.2 通过Swagger UI测试API

Swagger UI 提供的测试功能可以帮助开发者验证API功能是否按照预期工作。测试过程通常包括以下步骤：

  1. 选择API端点 ：在导航栏中选择希望测试的API端点。
  2. 配置请求参数 ：在请求参数区域中填入必要的参数值。
  3. 选择HTTP方法 ：使用请求方法选择下拉菜单，选择合适的HTTP方法。
  4. 执行请求 ：点击“Try it out”按钮后，再点击“Execute”执行API请求。
  5. 查看响应 ：观察响应区域，分析返回的响应数据是否符合预期。

5.2 API文档化的重要性

5.2.1 生成交互式的API文档

Swagger不仅仅为API提供了文档化，还创建了一个交互式的环境，用户可以在其中实时测试API。以下是生成交互式API文档的几个关键步骤：

  1. 定义API路径和操作 ：通过控制器和动作方法定义API的路径和操作。
  2. 描述API响应 ：使用Swagger注解来描述每个动作方法返回的数据结构和状态码。
  3. 集成OAuth 2.0 ：配置安全定义和令牌获取流程，以保护敏感API端点。
  4. 启用Swagger UI ：在项目中启用Swagger UI，将API定义转换成用户友好的Web界面。

5.2.2 文档的用户体验和可读性提升

良好的API文档应当具备易读性和易用性，以提高用户体验：

  • 简洁明了的界面设计 ：Swagger UI具备清晰的布局和直观的操作流程，使API消费者能够快速地了解API的用途和功能。
  • 文档的个性化 ：可以对Swagger UI进行定制，以展示开发者希望强调的API特性或规则。
  • 多语言支持 ：Swagger UI支持多种语言，从而可以让不同语言背景的开发者都能够理解API文档。

5.2.3 确保文档与API实现的一致性

文档的一致性是API文档化过程中不可或缺的一部分。确保文档与API实现一致，需要考虑以下因素：

  • 持续集成（CI） ：将文档生成作为CI流程的一部分，确保每次代码更改时文档都会更新。
  • 自动化测试 ：使用自动化测试工具来验证文档中的信息是否与代码实现保持一致。
  • 版本控制 ：对于API变更，及时更新文档，并记录版本历史，以便追踪API的演进。

5.3.4 代码示例：配置Swagger UI以测试API

在.NET Core项目中配置Swagger UI，首先需要安装Swagger相关的NuGet包：

dotnet add package Swashbuckle.AspNetCore

然后在Startup.cs文件中启用和配置Swagger服务：

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

以上配置将为API生成Swagger UI，允许用户通过浏览器访问 http://localhost:5000/swagger 来测试API。用户可以通过点击“Try it out”按钮，输入必要的请求参数，然后点击“Execute”来测试API端点的功能。

在这个过程中，开发者可以实时看到API的响应，确保API能够按照预期工作。这样的交互性测试有助于开发者及时发现并解决API实现中的问题。

6. 示例代码实现Swagger服务和JWT认证配置

在前几章中，我们已经深入了解了.NET Core MVC Web服务的基础知识、Swagger集成与令牌身份验证机制等。现在，让我们将理论付诸实践，通过以下示例代码来实现Swagger服务和JWT认证配置。

6.1 创建一个.NET Core MVC Web服务项目

6.1.1 初始化.NET Core MVC项目

首先，使用Visual Studio或者命令行工具，创建一个新的.NET Core MVC Web服务项目。这里假设我们使用.NET Core 3.1作为基础框架。

dotnet new mvc -n MySwaggerService
cd MySwaggerService

6.1.2 添加必要的依赖和服务配置

接下来，添加Swagger和JWT认证相关的NuGet包依赖，并在Startup.cs中配置服务。

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // 添加Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Swagger Service", Version = "v1" });
    });

    // 配置JWT认证服务
    var key = Encoding.ASCII.GetBytes("your_secret_key"); // 一个简单的密钥用于演示
    services.AddAuthentication(x =>
    {
        x.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        x.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    .AddJwtBearer(x =>
    {
        x.RequireHttpsMetadata = false;
        x.SaveToken = true;
        x.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = new SymmetricSecurityKey(key),
            ValidateIssuer = false,
            ValidateAudience = false
        };
    });
}

6.2 集成Swagger和配置JWT认证

6.2.1 实现Swagger服务的配置代码

在 Startup.cs 的 Configure 方法中启用Swagger服务，并配置中间件以使用Swagger生成的UI。

// Startup.cs

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 其他中间件配置...

    // 启用Swagger中间件
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Swagger Service V1");
    });

    // 其他中间件配置...
}

6.2.2 编写JWT认证的实现代码

创建一个简单的控制器用于演示JWT令牌的生成。

// HomeController.cs

[ApiController]
[Route("[controller]")]
public class HomeController : ControllerBase
{
    // GET: /home/login
    [HttpPost("login")]
    public IActionResult Login()
    {
        var token = GenerateToken();
        return Ok(new { token = token });
    }

    private string GenerateToken()
    {
        var key = Encoding.ASCII.GetBytes("your_secret_key");
        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(new Claim[]
            {
                new Claim(ClaimTypes.Name, "username")
            }),
            Expires = DateTime.UtcNow.AddDays(1),
            SigningCredentials = new SigningCredentials(new SymmetricSecurityKey(key), SecurityAlgorithms.HmacSha256Signature)
        };
        var tokenHandler = new JwtSecurityTokenHandler();
        var token = tokenHandler.CreateToken(tokenDescriptor);
        return tokenHandler.WriteToken(token);
    }
}

6.2.3 将Swagger与JWT认证集成的完整示例

确保在 Startup.cs 中配置了认证中间件，并在Swagger UI中启用OAuth 2.0流程。

// Startup.cs

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 其他中间件配置...

    // 启用认证中间件
    app.UseAuthentication();
    app.UseAuthorization();

    // 启用Swagger中间件
    // ...

    // 其他中间件配置...
}

6.3 运行和测试集成的Swagger与JWT认证

6.3.1 启动Web服务并测试Swagger UI

通过运行以下命令来启动Web服务：

dotnet run

访问Swagger UI ( http://localhost:<port>/swagger )，并测试登录端点（ /home/login ）来获取JWT令牌。

6.3.2 验证JWT令牌的生成和使用流程

复制从 /home/login 端点返回的令牌，并尝试在Swagger UI中使用它来访问需要认证的API端点。

6.3.3 检查API文档的完整性和可用性

验证生成的API文档是否准确反映了项目中的所有端点，并确保文档是交互式的，允许用户直接在文档中测试API。

sequenceDiagram
    participant U as 用户
    participant SW as Swagger UI
    participant API as Web API

    U->>SW: 访问Swagger UI
    SW->>API: 请求API文档
    API-->>SW: 返回API文档
    U->>SW: 使用登录端点获取JWT令牌
    SW->>API: 发送请求带JWT令牌
    API-->>SW: 返回认证后的API响应
    U->>SW: 测试其他API端点
    SW->>API: 发送请求带JWT令牌
    API-->>SW: 返回预期响应

在这个示例中，我们已经通过真实的代码示例演示了Swagger服务和JWT认证的集成过程。接下来的步骤包括：运行服务、测试Swagger UI、验证JWT令牌流程，并检查API文档的可用性。通过以上步骤，我们确保了Swagger与.NET Core MVC Web服务项目的成功集成，并且已经配置了 JWT 认证机制。

本文还有配套的精品资源，点击获取 menu-r.4af5f7ec.gif

简介：本文介绍如何在使用.NET Core MVC框架构建的Web服务中集成Swagger API工具，并实现令牌身份验证。Swagger允许开发者交互、测试和文档化API，而令牌身份验证通过OAuth 2.0或JWT保证API安全性。内容包括.NET Core MVC Web服务概念、Swagger集成、令牌身份验证原理和配置，以及如何使用Swagger UI测试和文档化API。文章还包括示例代码，展示如何在项目中配置Swagger服务和JWT认证服务。


本文还有配套的精品资源，点击获取
menu-r.4af5f7ec.gif

Logo
长沙城市开发者社区

惟楚有才，于斯为盛。欢迎来到长沙！！！ 茶颜悦色、臭豆腐、CSDN和你一个都不能少~

更多推荐

cover

2025 科技前沿全景：从量子突破到星际凝望的文明跃迁

avatar 长沙城市开发者社区

AIGC技术革新编程界新势力崛起AI赋能未来编程之道

分布式ID生成：Snowflake算法在异步环境的实现

avatar 长沙城市开发者社区

AIGC投资潜力AI生成内容投资攻略抓住未来风口

I/O密集型优化：gevent monkey patch的副作用

avatar 长沙城市开发者社区