api flattener & desc

src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs

@@ -5,7 +5,7 @@
 using System.Net;
 using System.Net.Mime;
 using System.Reflection;
-
+using System.Text.RegularExpressions;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Net.Http.Headers;
 using Microsoft.OpenApi.Any;
@@ -99,6 +99,7 @@ public static void Configure(SwaggerGenOptions swaggerGenOptions, string assembl
 				In = ParameterLocation.Header,
 				Type = SecuritySchemeType.Http,
 				Name = HeaderNames.Authorization,
+				Description = "Username & Password authentication to obtain an JWT token when doing a (POST /api).",
 				Scheme = ApiHeaders.BasicAuthenticationScheme,
 			});
 
@@ -107,16 +108,18 @@ public static void Configure(SwaggerGenOptions swaggerGenOptions, string assembl
 				In = ParameterLocation.Header,
 				Type = SecuritySchemeType.Http,
 				Name = HeaderNames.Authorization,
+				Description = "OAuth2 based authentication.",
 				Scheme = ApiHeaders.OAuthAuthenticationScheme,
 			});
 
 			swaggerGenOptions.AddSecurityDefinition(TokenSecuritySchemeId, new OpenApiSecurityScheme
 			{
-				BearerFormat = "JWT",
 				In = ParameterLocation.Header,
 				Type = SecuritySchemeType.Http,
 				Name = HeaderNames.Authorization,
+				Description = "JWT Bearer token generated by the server (POST /api). You need this for most endpoints to work.",
 				Scheme = ApiHeaders.BearerAuthenticationScheme,
+				BearerFormat = "JWT",
 			});
 		}
 
@@ -368,14 +371,11 @@ public void Apply(OpenApiOperation operation, OperationFilterContext context)
 					},
 				};
 
-				operation.Security = new List<OpenApiSecurityRequirement>
+				operation.Security = new List<OpenApiSecurityRequirement>()
 				{
 					new()
 					{
-						{
-							tokenScheme,
-							new List<string>()
-						},
+						{ tokenScheme, new List<string>() },
 					},
 				};
 
@@ -493,7 +493,6 @@ public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
 			var productHeaderSchema = new OpenApiSchema
 			{
 				Type = "string",
-				Format = "productheader",
 			};
 
 			swaggerDoc.Components.Parameters.Add(ApiHeaders.ApiVersionHeader, new OpenApiParameter
@@ -541,6 +540,28 @@ public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
 							Id = HeaderNames.UserAgent,
 						},
 					});
+
+					// flatten (Tgstation.Server.*).MyClass
+					if (operation.Description?.Length > 0)
+						operation.Description = Regex.Replace(operation.Description, @"Tgstation\.Server\.(\w+\.)+(?=\w+)", string.Empty);
+
+					if (operation.Summary?.Length > 0)
+						operation.Summary = Regex.Replace(operation.Summary, @"Tgstation\.Server\.(\w+\.)+(?=\w+)", string.Empty);
+
+					if (operation.RequestBody?.Description != null)
+						operation.RequestBody.Description = Regex.Replace(operation.RequestBody.Description, @"Tgstation\.Server\.(\w+\.)+(?=\w+)", string.Empty);
+
+					foreach (var opPar in operation.Parameters)
+					{
+						if (opPar.Description != null)
+							opPar.Description = Regex.Replace(opPar.Description, @"Tgstation\.Server\.(\w+\.)+(?=\w+)", string.Empty);
+					}
+
+					foreach (var (_, opRes) in operation.Responses)
+					{
+						if (opRes.Description != null)
+							opRes.Description = Regex.Replace(opRes.Description, @"Tgstation\.Server\.(\w+\.)+(?=\w+)", string.Empty);
+					}
 				}
 
 			AddDefaultResponses(swaggerDoc);