再谈Swagger：配置OAuth2认证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 添加 Swagger 服务
services.AddSwaggerGen(c =>
{
	c.SwaggerDoc("v1", new OpenApiInfo 
	{ 
		Title = "My API",
		Version = "v1"
		Description = "OpenAPI document based on OpenAPI 3.0 specification",
		Contact = new OpenApiContact
		{
			Email = "apiteam@swagger.io"
		}
	});
});

1
2
3
4
5
6
// 启用 Swagger 中间件
app.UseSwagger();
app.UseSwaggerUI(c => 
{
	c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/// <summary>  
/// Generates a hash for the provided URL string.  
/// The hash is used for uniquely identifying URLs in a consistent manner.  
/// </summary>  
/// <param name="target">The URL string to be hashed, provided in the request body.</param>  
/// <returns>  
/// Returns HTTP 200 OK with the hash value in the format "uHighPart:uLowPart".  
/// </returns>  
/// <response code="200">Returns the hash value in the format "uHighPart:uLowPart".</response>  
/// <response code="500">Internal server error. The backend response is invalid or an exception occurred.</response>  
[HttpPost("url-hash")]  
[SwaggerOperation(OperationId = "GenerateURLHash")]  
[Authorize(Policy = "User", AuthenticationSchemes = "AzureAd, AzureAdPME")]
[ProducesResponseType(typeof(string), StatusCodes.Status200OK)]  
[ProducesResponseType(StatusCodes.Status500InternalServerError)]  
public IActionResult GenerateURLHash([FromBody] string target)  
{  
	var urlHash = UrlHashHelper.GetUrlHash(target);  
	return Ok($"{urlHash.uHighPart}:{urlHash.uLowPart}");  
}

1
2
3
4
5
6
7
8
services.AddSwaggerGen(c =>
{
    // 加载项目的 XML 注释文件
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // true是包括Controller的XML注释
    c.IncludeXmlComments(xmlPath, true);
});

1
2
/// Returns HTTP 200 OK with the hash value in the format "uHighPart:uLowPart".
[ProducesResponseType(typeof(string), StatusCodes.Status200OK)]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
using Microsoft.OpenApi.Any;  
using System.Xml.Linq;  
using Microsoft.OpenApi.Models;  
using Swashbuckle.AspNetCore.SwaggerGen;

namespace SFSCorpTool.Controller.Interceptor  
{  
    /// <summary>  
    /// Schema filter that reads example tags from XML comments and sets them as Swagger property examples.  
    /// </summary>  
    public class XmlExampleSchemaFilter : ISchemaFilter  
    {  
        private readonly XDocument _xmlComments;

        /// <summary>  
        /// Loads the XML documentation file.  
        /// </summary>  
        /// <param name="xmlPath">Path to the XML documentation file.</param>  
        public XmlExampleSchemaFilter(string xmlPath)  
        {  
            _xmlComments = XDocument.Load(xmlPath);  
        }

        /// <summary>  
        /// Applies the example values from XML comments to the Swagger schema properties.  
        /// </summary>  
        /// <param name="schema">The OpenApiSchema to modify.</param>  
        /// <param name="context">The schema filter context.</param>  
        public void Apply(OpenApiSchema schema, SchemaFilterContext context)  
        {  
            var type = context.Type;

            // Iterate over all public properties of the type  
            foreach (var property in type.GetProperties())  
            {  
                // Construct the XML documentation member name for the property  
                var memberName = $"P:{type.FullName}.{property.Name}";  
                // Find the corresponding <member> node in the XML  
                var node = _xmlComments.Descendants("member").FirstOrDefault(m => m.Attribute("name")?.Value == memberName);

                // Get the value of the <example> tag, if present  
                var example = node?.Element("example")?.Value;  
                // If an example exists and the schema contains this property, set the example  
                if (example != null && schema.Properties.ContainsKey(property.Name))  
                {  
                    var propSchema = schema.Properties[property.Name];

                    // Try to parse the example as int, bool, or fallback to string  
                    if (int.TryParse(example, out var intVal))  
                        propSchema.Example = new OpenApiInteger(intVal);  
                    else if (bool.TryParse(example, out var boolVal))  
                        propSchema.Example = new OpenApiBoolean(boolVal);  
                    else  
                        propSchema.Example = new OpenApiString(example);  
                }  
                // If <example> is missing, nothing happens and no error is thrown  
            }  
        }  
    }  
}

1
2
3
4
services.AddSwaggerGen(c =>
{
	c.SchemaFilter<XmlExampleSchemaFilter>(xmlPath);
});

1
2
3
4
5
6
7
8
9
10
11
services.AddSwaggerGen(c =>
{
	c.AddSecurityDefinition("bearer", new OpenApiSecurityScheme
	{
		Description = "JWT Authentication, please input: Bearer {token}",
		Name = "Authorization",
		In = ParameterLocation.Header,
		Type = SecuritySchemeType.ApiKey,
		Schema = "bearer"
	});
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
c.AddSecurityRequirement(new OpenApiSecurityRequirement()
{
	{
		new OpenApiSecurityScheme
		{
			Reference = new OpenApiReference
			{
				Type = ReferenceType.SecurityScheme,
				Id = "bearer"
			}
		},
		Array.Empty<string>()
	}
});

1
c.OperationFilter<SecurityRequirementsOperationFilter>();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
services.AddSwaggerGen(c =>
{
	c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme  
	{  
		Name = "Authorization",  
		In = ParameterLocation.Header,  
		Type = SecuritySchemeType.OAuth2,  
		Scheme = "bearer",  
		BearerFormat = "JWT",  
		Flows = new OpenApiOAuthFlows  
		{  
			AuthorizationCode = new OpenApiOAuthFlow  
			{  
				AuthorizationUrl = new Uri($"{Configuration["AzureAd:Instance"]}{Configuration["AzureAd:TenantId"]}/oauth2/v2.0/authorize"),  
				TokenUrl = new Uri($"{Configuration["AzureAd:Instance"]}{Configuration["AzureAd:TenantId"]}/oauth2/v2.0/token"),  
				Scopes = new Dictionary<string, string>  
				{  
					{ $"api://{Configuration["AzureAd:ClientId"]}/user_impersonation", "Access the API as the signed-in user" },  
				}  
			}  
		}  
	});
});

1
2
3
4
5
6
7
8
9
app.UseSwaggerUI(opt =>  
{  
    opt.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");  
    opt.OAuthClientId(Configuration["AzureAd:ClientId"]);
    // 使用 PKCE，避免 client_secret
	opt.OAuthUsePkce();
	// 验证时自动勾选的scope
opt.OAuthScopes($"api://{Configuration["AzureAd:ClientId"]}/user_impersonation");
});

1
2
3
4
5
[ApiController]  
[Route("api/[controller]")]  
[ApiExplorerSettings(IgnoreApi = true)]  
[Authorize(Policy = "User", AuthenticationSchemes = "AzureAd, AzureAdPME")]
public class ChatBoxController : ControllerBase