Merge branch 'dev' of https://github.com/tgstation/tgstation-server into PreLaunchEvent

build/Version.props

@@ -8,7 +8,7 @@
     <TgsRestVersion>10.12.0</TgsRestVersion>
     <TgsGraphQLVersion>0.5.0</TgsGraphQLVersion>
     <TgsCommonLibraryVersion>7.0.0</TgsCommonLibraryVersion>
-    <TgsApiLibraryVersion>17.0.0</TgsApiLibraryVersion>
+    <TgsApiLibraryVersion>17.0.1</TgsApiLibraryVersion>
     <TgsClientVersion>20.0.0</TgsClientVersion>
     <TgsDmapiVersion>7.3.1</TgsDmapiVersion>
     <TgsInteropVersion>5.10.0</TgsInteropVersion>

build/stylecop.json

@@ -5,7 +5,8 @@
       "documentPrivateElements": true,
       "documentPrivateFields": true,
       "excludeFromPunctuationCheck": [
-        "remarks"
+        "remarks",
+        "example"
       ]
     },
     "indentation": {

src/Tgstation.Server.Api/Models/ChatChannel.cs

@@ -14,6 +14,7 @@ namespace Tgstation.Server.Api.Models
 		/// For <see cref="ChatProvider.Irc"/>, it's the IRC channel name and optional password colon separated.
 		/// For <see cref="ChatProvider.Discord"/>, it's the stringified Discord channel snowflake.
 		/// </summary>
+		/// <example>124823852418</example>
 		[Required]
 		[StringLength(Limits.MaximumIndexableStringLength, MinimumLength = 1)]
 		public string? ChannelData { get; set; }

src/Tgstation.Server.Api/Models/EngineVersion.cs

@@ -26,12 +26,14 @@ namespace Tgstation.Server.Api.Models
 		/// <summary>
 		/// The <see cref="System.Version"/> of the engine. Currently only valid when <see cref="Engine"/> is <see cref="EngineType.Byond"/>.
 		/// </summary>
+		/// <example>516.1651.0</example>
 		[ResponseOptions]
 		public Version? Version { get; set; }
 
 		/// <summary>
 		/// The git commit SHA of the engine. Currently only valid when <see cref="Engine"/> is <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>caa1e1f400c8b6a535e03cff28cf57f919e9378c</example>
 		[ResponseOptions]
 		[StringLength(Limits.MaximumCommitShaLength, MinimumLength = Limits.MaximumCommitShaLength)]
 		public string? SourceSHA { get; set; }

src/Tgstation.Server.Api/Models/EntityId.cs

@@ -8,6 +8,7 @@
 		/// <summary>
 		/// The ID of the entity.
 		/// </summary>
+		/// <example>1</example>
 		[RequestOptions(FieldPresence.Required)]
 		[RequestOptions(FieldPresence.Ignored, PutOnly = true)]
 		public virtual long? Id { get; set; }

src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs

@@ -16,6 +16,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The time interval in minutes the chat bot attempts to reconnect if <see cref="Enabled"/> and disconnected. Must not be zero.
 		/// </summary>
+		/// <example>60</example>
 		[Required]
 		[Range(1, UInt32.MaxValue)]
 		public uint? ReconnectionInterval { get; set; }
@@ -23,6 +24,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The maximum number of <see cref="ChatChannel"/>s the <see cref="ChatBotSettings"/> may contain.
 		/// </summary>
+		/// <example>5</example>
 		[Required]
 		public ushort? ChannelLimit { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs

@@ -10,18 +10,21 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// If the <see cref="ChatChannel"/> is an admin channel.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? IsAdminChannel { get; set; }
 
 		/// <summary>
 		/// If the <see cref="ChatChannel"/> is a watchdog channel.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? IsWatchdogChannel { get; set; }
 
 		/// <summary>
 		/// If the <see cref="ChatChannel"/> is an updates channel.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? IsUpdatesChannel { get; set; }
 
@@ -34,6 +37,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// A custom tag users can define to group channels together.
 		/// </summary>
+		/// <example>system-channel-only</example>
 		[ResponseOptions]
 		[StringLength(Limits.MaximumStringLength)]
 		public string? Tag { get; set; }

src/Tgstation.Server.Api/Models/Internal/CompileJob.cs

@@ -12,6 +12,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The .dme file used for compilation.
 		/// </summary>
+		/// <example>tgstation.dme</example>
 		[Required]
 		public string? DmeName { get; set; }
 
@@ -36,6 +37,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The DMAPI <see cref="Version"/>.
 		/// </summary>
+		/// <example>7.3.0</example>
 		[NotMapped]
 		[ResponseOptions]
 		public virtual Version? DMApiVersion { get; set; }

src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs

@@ -10,6 +10,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// An incrementing ID for representing current server execution.
 		/// </summary>
+		/// <example>1</example>
 		[ResponseOptions]
 		public long? SessionId { get; set; }
 
@@ -22,12 +23,14 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The last known count of connected players. Requires <see cref="DreamDaemonLaunchParameters.HealthCheckSeconds"/> to not be 0 and a game server interop version >= 5.10.0 to populate.
 		/// </summary>
+		/// <example>30</example>
 		[ResponseOptions]
 		public uint? ClientCount { get; set; }
 
 		/// <summary>
 		/// If the server is undergoing a soft reset. This may be automatically set by changes to other fields.
 		/// </summary>
+		/// <example>false</example>
 		[ResponseOptions]
 		public bool? SoftRestart { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs

@@ -11,6 +11,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// If the BYOND web client can be used to connect to the game server. No-op for <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		[ResponseOptions]
 		public bool? AllowWebClient { get; set; }
@@ -25,6 +26,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The <see cref="DreamDaemonVisibility"/> level of DreamDaemon. No-op for <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>2</example>
 		[Required]
 		[ResponseOptions]
 		[EnumDataType(typeof(DreamDaemonVisibility))]
@@ -33,6 +35,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The <see cref="DreamDaemonSecurity"/> level of DreamDaemon. No-op for <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>1</example>
 		[Required]
 		[ResponseOptions]
 		[EnumDataType(typeof(DreamDaemonSecurity))]
@@ -41,6 +44,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The port DreamDaemon uses. This should be publically accessible.
 		/// </summary>
+		/// <example>1337</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt16.MaxValue)]
@@ -49,6 +53,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The port used by <see cref="EngineType.OpenDream"/> for its topic port.
 		/// </summary>
+		/// <example>2337</example>
 		[Required]
 		[ResponseOptions]
 		public ushort? OpenDreamTopicPort { get; set; }
@@ -56,6 +61,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The DreamDaemon startup timeout in seconds.
 		/// </summary>
+		/// <example>5</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt32.MaxValue)]
@@ -64,6 +70,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The number of seconds between each watchdog health check. 0 disables.
 		/// </summary>
+		/// <example>5</example>
 		[Required]
 		[ResponseOptions]
 		public uint? HealthCheckSeconds { get; set; }
@@ -78,6 +85,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The timeout for sending and receiving BYOND topics in milliseconds.
 		/// </summary>
+		/// <example>500</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt32.MaxValue)]

src/Tgstation.Server.Api/Models/Internal/Job.cs

@@ -20,6 +20,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// English description of the <see cref="Job"/>.
 		/// </summary>
 		/// <remarks>May not match the <see cref="System.ComponentModel.DescriptionAttribute"/> listed on the <see cref="Models.JobCode"/>.</remarks>
+		/// <example>Installing and configuring important objects.</example>
 		[Required]
 		public string? Description { get; set; }
 
@@ -50,6 +51,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// If the <see cref="Job"/> was cancelled.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? Cancelled { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs

@@ -10,26 +10,31 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// Minimum length of database user passwords.
 		/// </summary>
+		/// <example>20</example>
 		public uint MinimumPasswordLength { get; set; }
 
 		/// <summary>
 		/// The maximum number of <see cref="Instance"/>s allowed.
 		/// </summary>
+		/// <example>100</example>
 		public uint InstanceLimit { get; set; }
 
 		/// <summary>
 		/// The maximum number of users allowed.
 		/// </summary>
+		/// <example>100</example>
 		public uint UserLimit { get; set; }
 
 		/// <summary>
 		/// The maximum number of user groups allowed.
 		/// </summary>
+		/// <example>50</example>
 		public uint UserGroupLimit { get; set; }
 
 		/// <summary>
 		/// Limits the locations instances may be created or attached from.
 		/// </summary>
+		/// <example>["/home/tgstation-server/my-server-1", "/home/tgstation-server/my-server-2"]</example>
 		[ResponseOptions]
 		public List<string>? ValidInstancePaths { get; set; }
 	}

src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs

@@ -22,6 +22,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The server's identifier.
 		/// </summary>
+		/// <example>myserver-us-east</example>
 		[Required]
 		public string? Identifier { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs

@@ -10,6 +10,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// If the <see cref="SwarmServerResponse"/> is the controller.
 		/// </summary>
+		/// <example>false</example>
 		public bool Controller { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs

@@ -11,6 +11,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The ID of the <see cref="TestMergeApiBase"/>.
 		/// </summary>
+		/// <example>1</example>
 		public long Id { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs

@@ -11,18 +11,21 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The title of the test merge source.
 		/// </summary>
+		/// <example>Fixes and Breaks everything</example>
 		[Required]
 		public string? TitleAtMerge { get; set; }
 
 		/// <summary>
 		/// The body of the test merge source.
 		/// </summary>
+		/// <example># GitHub markdown\n\rI assume?</example>
 		[Required]
 		public string? BodyAtMerge { get; set; }
 
 		/// <summary>
 		/// The URL of the test merge source.
 		/// </summary>
+		/// <example>https://github.com/tgstation/tgstation/pull/31026</example>
 		[Required]
 #pragma warning disable CA1056 // Uri properties should not be strings
 		public string? Url { get; set; }
@@ -31,6 +34,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The author of the test merge source.
 		/// </summary>
+		/// <example>MrStonedOne</example>
 		[Required]
 		public string? Author { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs

@@ -10,6 +10,7 @@ namespace Tgstation.Server.Api.Models.Internal
 		/// <summary>
 		/// The latest available version of the Tgstation.Server.Host assembly from the upstream repository. If <see cref="Version.Major"/> is less than 4 the update cannot be applied due to API changes.
 		/// </summary>
+		/// <example>1.0.0</example>
 		public Version? LatestVersion { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/NamedEntity.cs

@@ -10,6 +10,7 @@ namespace Tgstation.Server.Api.Models
 		/// <summary>
 		/// The name of the entity represented by the <see cref="NamedEntity"/>.
 		/// </summary>
+		/// <example>MyThingyName</example>
 		[Required]
 		[RequestOptions(FieldPresence.Required, PutOnly = true)]
 		[StringLength(Limits.MaximumIndexableStringLength, MinimumLength = 1)]

src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs

@@ -10,6 +10,7 @@ namespace Tgstation.Server.Api.Models.Request
 		/// <summary>
 		/// Changes the version of tgstation-server to the given version from the upstream repository.
 		/// </summary>
+		/// <example>6.12.3</example>
 		[RequestOptions(FieldPresence.Required)]
 		public Version? NewVersion { get; set; }
 

src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs

@@ -12,6 +12,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The GitHub repository the server is built to receive updates from.
 		/// </summary>
+		/// <example>https://github.com/tgstation/tgstation</example>
 		public Uri? TrackedRepositoryUrl { get; set; }
 	}
 }

src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs

@@ -24,6 +24,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The current <see cref="WatchdogStatus"/>.
 		/// </summary>
+		/// <example>2</example>
 		[EnumDataType(typeof(WatchdogStatus))]
 		[ResponseOptions]
 		public WatchdogStatus? Status { get; set; }
@@ -31,6 +32,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The current <see cref="DreamDaemonSecurity"/>. May be upgraded. due to requirements of <see cref="ActiveCompileJob"/>.
 		/// </summary>
+		/// <example>1</example>
 		[EnumDataType(typeof(DreamDaemonSecurity))]
 		[ResponseOptions]
 		public DreamDaemonSecurity? CurrentSecurity { get; set; }
@@ -38,6 +40,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The current <see cref="DreamDaemonVisibility"/>.
 		/// </summary>
+		/// <example>2</example>
 		[EnumDataType(typeof(DreamDaemonVisibility))]
 		[ResponseOptions]
 		public DreamDaemonVisibility? CurrentVisibility { get; set; }
@@ -45,24 +48,28 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The port the running <see cref="DreamDaemonResponse"/> instance is set to.
 		/// </summary>
+		/// <example>1337</example>
 		[ResponseOptions]
 		public ushort? CurrentPort { get; set; }
 
 		/// <summary>
 		/// The <see cref="EngineType.OpenDream"/> topic port the running <see cref="DreamDaemonResponse"/> instance is set to.
 		/// </summary>
+		/// <example>3000</example>
 		[ResponseOptions]
 		public ushort? CurrentTopicPort { get; set; }
 
 		/// <summary>
 		/// The webclient status the running <see cref="DreamDaemonResponse"/> instance is set to.
 		/// </summary>
+		/// <example>false</example>
 		[ResponseOptions]
 		public bool? CurrentAllowWebclient { get; set; }
 
 		/// <summary>
 		/// The amount of RAM in use by the game server in bytes.
 		/// </summary>
+		/// <example>1073741824</example>
 		[ResponseOptions]
 		public long? ImmediateMemoryUsage { get; set; }
 	}

src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs

@@ -13,16 +13,19 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The version of the API the server is using.
 		/// </summary>
+		/// <example>9.3.0</example>
 		public Version? ServerApiVersion { get; set; }
 
 		/// <summary>
-		/// A human readable description of the error.
+		/// A human-readable description of the error.
 		/// </summary>
+		/// <example>Oopsie woopsie, we did a fucky wucky!</example>
 		public string? Message { get; set; }
 
 		/// <summary>
 		/// Additional data associated with the error message.
 		/// </summary>
+		/// <example>Error at thing.app.dependency.class.function in line 32</example>
 		[ResponseOptions]
 		public string? AdditionalData { get; set; }
 

src/Tgstation.Server.Api/Models/Response/JobResponse.cs

@@ -8,6 +8,7 @@
 		/// <summary>
 		/// The <see cref="EntityId.Id"/> of the <see cref="Instance"/>.
 		/// </summary>
+		/// <example>1</example>
 		public long? InstanceId { get; set; }
 
 		/// <summary>
@@ -24,12 +25,14 @@
 		/// <summary>
 		/// Optional progress between 0 and 100 inclusive.
 		/// </summary>
+		/// <example>25</example>
 		[ResponseOptions]
 		public int? Progress { get; set; }
 
 		/// <summary>
-		/// Optional description of the job's current .
+		/// Optional description of the job's current progress.
 		/// </summary>
+		/// <example>Doing something important</example>
 		[ResponseOptions]
 		public string? Stage { get; set; }
 	}

src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs

@@ -10,6 +10,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The name of the log file.
 		/// </summary>
+		/// <example>tgs-20250118.log</example>
 		public string? Name { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs

@@ -18,16 +18,19 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The total number of pages in the query.
 		/// </summary>
+		/// <example>5</example>
 		public int TotalPages { get; set; }
 
 		/// <summary>
 		/// The current size of pages in the query.
 		/// </summary>
+		/// <example>20</example>
 		public int PageSize { get; set; }
 
 		/// <summary>
 		/// The total items across all pages.
 		/// </summary>
+		/// <example>100</example>
 		public int TotalItems { get; set; }
 	}
 }

src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs

@@ -11,16 +11,19 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The version of the host.
 		/// </summary>
+		/// <example>6.12.3</example>
 		public Version? Version { get; set; }
 
 		/// <summary>
 		/// The <see cref="Api"/> version of the host.
 		/// </summary>
+		/// <example>10.12.0</example>
 		public Version? ApiVersion { get; set; }
 
 		/// <summary>
 		/// The DMAPI interop version the server uses.
 		/// </summary>
+		/// <example>7.3.0</example>
 		public Version? DMApiVersion { get; set; }
 
 		/// <summary>
@@ -36,6 +39,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// If there is a server update in progress.
 		/// </summary>
+		/// <example>false</example>
 		public bool UpdateInProgress { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs

@@ -12,6 +12,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The version of tgstation-server pending update.
 		/// </summary>
+		/// <example>6.12.3</example>
 		public Version NewVersion { get; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/Response/TokenResponse.cs

@@ -10,6 +10,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// The value of the JWT.
 		/// </summary>
+		/// <example>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmJmIjoxNzM3MDkzNDgwLCJleHAiOjE3MzcwOTQzODAsImlhdCI6MTczNzA5MzQ4MCwiaXNzIjoiVGdzdGF0aW9uLlNlcnZlci5Ib3N0IiwiYXVkIjoiVGdzdGF0aW9uLlNlcnZlci5BcGkifQ.v64KX34_YOpH-HCbwqlx1p8u-MNbb4L6a9qEyXhcNcU</example>
 		public string? Bearer { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/TestMergeParameters.cs

@@ -10,18 +10,21 @@ namespace Tgstation.Server.Api.Models
 		/// <summary>
 		/// The number of the test merge source.
 		/// </summary>
+		/// <example>31026</example>
 		public int Number { get; set; }
 
 		/// <summary>
 		/// The sha of the test merge revision to merge. If not specified, the latest commit from the source will be used.
 		/// </summary>
+		/// <example>caa1e1f400c8b6a535e03cff28cf57f919e9378c</example>
 		[Required]
-		[StringLength(40)]
+		[StringLength(Limits.MaximumCommitShaLength, MinimumLength = Limits.MaximumCommitShaLength)]
 		public virtual string? TargetCommitSha { get; set; }
 
 		/// <summary>
 		/// Optional comment about the test.
 		/// </summary>
+		/// <example>this will fix everything -Admin</example>
 		[ResponseOptions]
 		[StringLength(Limits.MaximumStringLength)]
 		public string? Comment { get; set; }

src/Tgstation.Server.Api/Models/UserName.cs

@@ -6,6 +6,7 @@
 	public class UserName : NamedEntity
 	{
 		/// <inheritdoc />
+		/// <example>Admin</example>
 		[RequestOptions(FieldPresence.Optional)]
 		public override string? Name
 		{

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

@@ -5,6 +5,7 @@ using System.Linq;
 using System.Net;
 using System.Net.Mime;
 using System.Reflection;
+using System.Text.RegularExpressions;
 
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Net.Http.Headers;
@@ -99,6 +100,7 @@ namespace Tgstation.Server.Host.Utils
 				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 +109,18 @@ namespace Tgstation.Server.Host.Utils
 				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 +372,11 @@ namespace Tgstation.Server.Host.Utils
 					},
 				};
 
-				operation.Security = new List<OpenApiSecurityRequirement>
+				operation.Security = new List<OpenApiSecurityRequirement>()
 				{
 					new()
 					{
-						{
-							tokenScheme,
-							new List<string>()
-						},
+						{ tokenScheme, new List<string>() },
 					},
 				};
 
@@ -493,7 +494,6 @@ namespace Tgstation.Server.Host.Utils
 			var productHeaderSchema = new OpenApiSchema
 			{
 				Type = "string",
-				Format = "productheader",
 			};
 
 			swaggerDoc.Components.Parameters.Add(ApiHeaders.ApiVersionHeader, new OpenApiParameter
@@ -541,6 +541,28 @@ namespace Tgstation.Server.Host.Utils
 							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);