From a6e4fc8b9343ea55f0ea34a0c96b2c609cc44321 Mon Sep 17 00:00:00 2001
From: LetterN <24603524+LetterN@users.noreply.github.com>
Date: Sun, 19 Jan 2025 17:44:52 +0800
Subject: [PATCH 1/2] <example>s

---
 build/stylecop.json                                       | 3 ++-
 src/Tgstation.Server.Api/Models/ChatChannel.cs            | 1 +
 src/Tgstation.Server.Api/Models/EngineVersion.cs          | 2 ++
 src/Tgstation.Server.Api/Models/EntityId.cs               | 1 +
 .../Models/Internal/ChatBotSettings.cs                    | 2 ++
 .../Models/Internal/ChatChannelBase.cs                    | 4 ++++
 src/Tgstation.Server.Api/Models/Internal/CompileJob.cs    | 2 ++
 .../Models/Internal/DreamDaemonApiBase.cs                 | 3 +++
 .../Models/Internal/DreamDaemonLaunchParameters.cs        | 8 ++++++++
 src/Tgstation.Server.Api/Models/Internal/Job.cs           | 2 ++
 .../Models/Internal/ServerInformationBase.cs              | 5 +++++
 src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs   | 1 +
 .../Models/Internal/SwarmServerInformation.cs             | 1 +
 .../Models/Internal/TestMergeApiBase.cs                   | 1 +
 .../Models/Internal/TestMergeModelBase.cs                 | 4 ++++
 .../Models/Internal/UpdateInformation.cs                  | 1 +
 src/Tgstation.Server.Api/Models/NamedEntity.cs            | 1 +
 .../Models/Request/ServerUpdateRequest.cs                 | 1 +
 .../Models/Response/AdministrationResponse.cs             | 1 +
 .../Models/Response/DreamDaemonResponse.cs                | 7 +++++++
 .../Models/Response/ErrorMessageResponse.cs               | 5 ++++-
 src/Tgstation.Server.Api/Models/Response/JobResponse.cs   | 5 ++++-
 .../Models/Response/LogFileResponse.cs                    | 1 +
 .../Models/Response/PaginatedResponse.cs                  | 3 +++
 .../Models/Response/ServerInformationResponse.cs          | 4 ++++
 .../Models/Response/ServerUpdateResponse.cs               | 1 +
 src/Tgstation.Server.Api/Models/Response/TokenResponse.cs | 1 +
 src/Tgstation.Server.Api/Models/TestMergeParameters.cs    | 5 ++++-
 src/Tgstation.Server.Api/Models/UserName.cs               | 1 +
 29 files changed, 73 insertions(+), 4 deletions(-)

diff --git a/build/stylecop.json b/build/stylecop.json
index d18cd8693c1..1ce8caabbd3 100644
--- a/build/stylecop.json
+++ b/build/stylecop.json
@@ -5,7 +5,8 @@
       "documentPrivateElements": true,
       "documentPrivateFields": true,
       "excludeFromPunctuationCheck": [
-        "remarks"
+        "remarks",
+        "example"
       ]
     },
     "indentation": {
diff --git a/src/Tgstation.Server.Api/Models/ChatChannel.cs b/src/Tgstation.Server.Api/Models/ChatChannel.cs
index 3192603e2b0..064711d76cd 100644
--- a/src/Tgstation.Server.Api/Models/ChatChannel.cs
+++ b/src/Tgstation.Server.Api/Models/ChatChannel.cs
@@ -14,6 +14,7 @@ public class ChatChannel : ChatChannelBase
 		/// 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; }
diff --git a/src/Tgstation.Server.Api/Models/EngineVersion.cs b/src/Tgstation.Server.Api/Models/EngineVersion.cs
index 61966105973..c84ee37eec6 100644
--- a/src/Tgstation.Server.Api/Models/EngineVersion.cs
+++ b/src/Tgstation.Server.Api/Models/EngineVersion.cs
@@ -26,12 +26,14 @@ public sealed class EngineVersion : IEquatable<EngineVersion>
 		/// <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; }
diff --git a/src/Tgstation.Server.Api/Models/EntityId.cs b/src/Tgstation.Server.Api/Models/EntityId.cs
index 43ac2e7edaf..c7660d399e6 100644
--- a/src/Tgstation.Server.Api/Models/EntityId.cs
+++ b/src/Tgstation.Server.Api/Models/EntityId.cs
@@ -8,6 +8,7 @@ public class EntityId
 		/// <summary>
 		/// The ID of the entity.
 		/// </summary>
+		/// <example>1</example>
 		[RequestOptions(FieldPresence.Required)]
 		[RequestOptions(FieldPresence.Ignored, PutOnly = true)]
 		public virtual long? Id { get; set; }
diff --git a/src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs b/src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs
index 4f6a9e2fac5..ecdd0a31100 100644
--- a/src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs
@@ -16,6 +16,7 @@ public abstract class ChatBotSettings : NamedEntity
 		/// <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 @@ public abstract class ChatBotSettings : NamedEntity
 		/// <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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs b/src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs
index eee19f244fc..cc0501d2b5f 100644
--- a/src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs
@@ -10,18 +10,21 @@ public abstract class ChatChannelBase
 		/// <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 @@ public abstract class ChatChannelBase
 		/// <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; }
diff --git a/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs b/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs
index eb8862a86c3..386a65a9fb7 100644
--- a/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs
@@ -12,6 +12,7 @@ public abstract class CompileJob : EntityId
 		/// <summary>
 		/// The .dme file used for compilation.
 		/// </summary>
+		/// <example>tgstation.dme</example>
 		[Required]
 		public string? DmeName { get; set; }
 
@@ -36,6 +37,7 @@ public abstract class CompileJob : EntityId
 		/// <summary>
 		/// The DMAPI <see cref="Version"/>.
 		/// </summary>
+		/// <example>7.3.0</example>
 		[NotMapped]
 		[ResponseOptions]
 		public virtual Version? DMApiVersion { get; set; }
diff --git a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs
index c0c6f63374f..116f27425d0 100644
--- a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs
@@ -10,6 +10,7 @@ public abstract class DreamDaemonApiBase : DreamDaemonSettings
 		/// <summary>
 		/// An incrementing ID for representing current server execution.
 		/// </summary>
+		/// <example>1</example>
 		[ResponseOptions]
 		public long? SessionId { get; set; }
 
@@ -22,12 +23,14 @@ public abstract class DreamDaemonApiBase : DreamDaemonSettings
 		/// <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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs
index 05bef48a50c..dca2356a9db 100644
--- a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs
@@ -11,6 +11,7 @@ public class DreamDaemonLaunchParameters
 		/// <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 @@ public class DreamDaemonLaunchParameters
 		/// <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 @@ public class DreamDaemonLaunchParameters
 		/// <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 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The port DreamDaemon uses. This should be publically accessible.
 		/// </summary>
+		/// <example>1337</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt16.MaxValue)]
@@ -49,6 +53,7 @@ public class DreamDaemonLaunchParameters
 		/// <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 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The DreamDaemon startup timeout in seconds.
 		/// </summary>
+		/// <example>5</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt32.MaxValue)]
@@ -64,6 +70,7 @@ public class DreamDaemonLaunchParameters
 		/// <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 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The timeout for sending and receiving BYOND topics in milliseconds.
 		/// </summary>
+		/// <example>500</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt32.MaxValue)]
diff --git a/src/Tgstation.Server.Api/Models/Internal/Job.cs b/src/Tgstation.Server.Api/Models/Internal/Job.cs
index 8b3b210c602..29a44c7803f 100644
--- a/src/Tgstation.Server.Api/Models/Internal/Job.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/Job.cs
@@ -20,6 +20,7 @@ public class Job : EntityId
 		/// 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 @@ public class Job : EntityId
 		/// <summary>
 		/// If the <see cref="Job"/> was cancelled.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? Cancelled { get; set; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs b/src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs
index 15fafe90b1d..9341662df38 100644
--- a/src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs
@@ -10,26 +10,31 @@ public abstract class ServerInformationBase
 		/// <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; }
 	}
diff --git a/src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs b/src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs
index 998c519b19c..3682306335e 100644
--- a/src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs
@@ -22,6 +22,7 @@ public abstract class SwarmServer
 		/// <summary>
 		/// The server's identifier.
 		/// </summary>
+		/// <example>myserver-us-east</example>
 		[Required]
 		public string? Identifier { get; set; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs b/src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs
index 89238b30990..6ea4ee92f39 100644
--- a/src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs
@@ -10,6 +10,7 @@ public class SwarmServerInformation : SwarmServer
 		/// <summary>
 		/// If the <see cref="SwarmServerResponse"/> is the controller.
 		/// </summary>
+		/// <example>false</example>
 		public bool Controller { get; set; }
 
 		/// <summary>
diff --git a/src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs b/src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs
index 036124c2a11..7b3a26cf333 100644
--- a/src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs
@@ -11,6 +11,7 @@ public class TestMergeApiBase : TestMergeModelBase
 		/// <summary>
 		/// The ID of the <see cref="TestMergeApiBase"/>.
 		/// </summary>
+		/// <example>1</example>
 		public long Id { get; set; }
 
 		/// <summary>
diff --git a/src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs b/src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs
index 20a2821d07b..d936f9f026b 100644
--- a/src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs
@@ -11,18 +11,21 @@ public abstract class TestMergeModelBase : TestMergeParameters
 		/// <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 @@ public abstract class TestMergeModelBase : TestMergeParameters
 		/// <summary>
 		/// The author of the test merge source.
 		/// </summary>
+		/// <example>MrStonedOne</example>
 		[Required]
 		public string? Author { get; set; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs b/src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs
index 9f049e48146..ea587a9d637 100644
--- a/src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs
+++ b/src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs
@@ -10,6 +10,7 @@ public class UpdateInformation
 		/// <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>
diff --git a/src/Tgstation.Server.Api/Models/NamedEntity.cs b/src/Tgstation.Server.Api/Models/NamedEntity.cs
index a138ef7eb55..930ca9c6e3b 100644
--- a/src/Tgstation.Server.Api/Models/NamedEntity.cs
+++ b/src/Tgstation.Server.Api/Models/NamedEntity.cs
@@ -10,6 +10,7 @@ public abstract class NamedEntity : EntityId
 		/// <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)]
diff --git a/src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs b/src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs
index ab34e28bde2..c3bf7b84258 100644
--- a/src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs
+++ b/src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs
@@ -10,6 +10,7 @@ public sealed class ServerUpdateRequest
 		/// <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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs b/src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs
index fbdd1f00a16..437dc6132a2 100644
--- a/src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs
@@ -12,6 +12,7 @@ public sealed class AdministrationResponse : UpdateInformation
 		/// <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; }
 	}
 }
diff --git a/src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs b/src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs
index d0b86cdaa41..115d2c395e6 100644
--- a/src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs
@@ -24,6 +24,7 @@ public sealed class DreamDaemonResponse : DreamDaemonApiBase
 		/// <summary>
 		/// The current <see cref="WatchdogStatus"/>.
 		/// </summary>
+		/// <example>2</example>
 		[EnumDataType(typeof(WatchdogStatus))]
 		[ResponseOptions]
 		public WatchdogStatus? Status { get; set; }
@@ -31,6 +32,7 @@ public sealed class DreamDaemonResponse : DreamDaemonApiBase
 		/// <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 @@ public sealed class DreamDaemonResponse : DreamDaemonApiBase
 		/// <summary>
 		/// The current <see cref="DreamDaemonVisibility"/>.
 		/// </summary>
+		/// <example>2</example>
 		[EnumDataType(typeof(DreamDaemonVisibility))]
 		[ResponseOptions]
 		public DreamDaemonVisibility? CurrentVisibility { get; set; }
@@ -45,24 +48,28 @@ public sealed class DreamDaemonResponse : DreamDaemonApiBase
 		/// <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; }
 	}
diff --git a/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs b/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
index 70cb64c530d..d58d81b6b4f 100644
--- a/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
@@ -13,16 +13,19 @@ public sealed class ErrorMessageResponse
 		/// <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>Ooopsie, 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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Response/JobResponse.cs b/src/Tgstation.Server.Api/Models/Response/JobResponse.cs
index 053fe1f9aaa..4e97485e95c 100644
--- a/src/Tgstation.Server.Api/Models/Response/JobResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/JobResponse.cs
@@ -8,6 +8,7 @@ public sealed class JobResponse : Internal.Job
 		/// <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 @@ public sealed class JobResponse : Internal.Job
 		/// <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; }
 	}
diff --git a/src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs b/src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs
index 05c05e8aa04..b39867b413e 100644
--- a/src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs
@@ -10,6 +10,7 @@ public sealed class LogFileResponse : FileTicketResponse
 		/// <summary>
 		/// The name of the log file.
 		/// </summary>
+		/// <example>tgs-20250118.log</example>
 		public string? Name { get; set; }
 
 		/// <summary>
diff --git a/src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs b/src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs
index df3d72595f0..dc42fa230c0 100644
--- a/src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs
@@ -18,16 +18,19 @@ public sealed class PaginatedResponse<TModel>
 		/// <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; }
 	}
 }
diff --git a/src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs b/src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs
index 4e80e80564f..82f27e7e7c5 100644
--- a/src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs
@@ -11,16 +11,19 @@ public sealed class ServerInformationResponse : Internal.ServerInformationBase
 		/// <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 @@ public sealed class ServerInformationResponse : Internal.ServerInformationBase
 		/// <summary>
 		/// If there is a server update in progress.
 		/// </summary>
+		/// <example>false</example>
 		public bool UpdateInProgress { get; set; }
 
 		/// <summary>
diff --git a/src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs b/src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs
index 48c9b99e6a1..46a96d8d49a 100644
--- a/src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs
@@ -12,6 +12,7 @@ public sealed class ServerUpdateResponse : FileTicketResponse
 		/// <summary>
 		/// The version of tgstation-server pending update.
 		/// </summary>
+		/// <example>6.12.3</example>
 		public Version NewVersion { get; }
 
 		/// <summary>
diff --git a/src/Tgstation.Server.Api/Models/Response/TokenResponse.cs b/src/Tgstation.Server.Api/Models/Response/TokenResponse.cs
index f81066741a4..ddc757dfd0f 100644
--- a/src/Tgstation.Server.Api/Models/Response/TokenResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/TokenResponse.cs
@@ -10,6 +10,7 @@ public sealed class TokenResponse
 		/// <summary>
 		/// The value of the JWT.
 		/// </summary>
+		/// <example>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmJmIjoxNzM3MDkzNDgwLCJleHAiOjE3MzcwOTQzODAsImlhdCI6MTczNzA5MzQ4MCwiaXNzIjoiVGdzdGF0aW9uLlNlcnZlci5Ib3N0IiwiYXVkIjoiVGdzdGF0aW9uLlNlcnZlci5BcGkifQ.v64KX34_YOpH-HCbwqlx1p8u-MNbb4L6a9qEyXhcNcU</example>
 		public string? Bearer { get; set; }
 
 		/// <summary>
diff --git a/src/Tgstation.Server.Api/Models/TestMergeParameters.cs b/src/Tgstation.Server.Api/Models/TestMergeParameters.cs
index 174bb6886b3..22b4b5f28e4 100644
--- a/src/Tgstation.Server.Api/Models/TestMergeParameters.cs
+++ b/src/Tgstation.Server.Api/Models/TestMergeParameters.cs
@@ -10,18 +10,21 @@ public class TestMergeParameters
 		/// <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; }
diff --git a/src/Tgstation.Server.Api/Models/UserName.cs b/src/Tgstation.Server.Api/Models/UserName.cs
index a3b6be81621..00f9b4772a1 100644
--- a/src/Tgstation.Server.Api/Models/UserName.cs
+++ b/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
 		{

From 16194fa88505b76a1d5d2faa003a6b34f171c632 Mon Sep 17 00:00:00 2001
From: LetterN <24603524+LetterN@users.noreply.github.com>
Date: Sun, 19 Jan 2025 17:45:38 +0800
Subject: [PATCH 2/2] api flattener & desc

---
 .../Utils/SwaggerConfiguration.cs             | 37 +++++++++++++++----
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs b/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs
index d415e30ea31..5c3c55313bb 100644
--- a/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs
+++ b/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);