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/3] <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 d18cd8693c..1ce8caabbd 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 3192603e2b..064711d76c 100644
--- a/src/Tgstation.Server.Api/Models/ChatChannel.cs
+++ b/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; }
diff --git a/src/Tgstation.Server.Api/Models/EngineVersion.cs b/src/Tgstation.Server.Api/Models/EngineVersion.cs
index 6196610597..c84ee37eec 100644
--- a/src/Tgstation.Server.Api/Models/EngineVersion.cs
+++ b/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; }
diff --git a/src/Tgstation.Server.Api/Models/EntityId.cs b/src/Tgstation.Server.Api/Models/EntityId.cs
index 43ac2e7eda..c7660d399e 100644
--- a/src/Tgstation.Server.Api/Models/EntityId.cs
+++ b/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; }
diff --git a/src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs b/src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs
index 4f6a9e2fac..ecdd0a3110 100644
--- a/src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs
+++ b/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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs b/src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs
index eee19f244f..cc0501d2b5 100644
--- a/src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs
+++ b/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; }
diff --git a/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs b/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs
index eb8862a86c..386a65a9fb 100644
--- a/src/Tgstation.Server.Api/Models/Internal/CompileJob.cs
+++ b/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; }
diff --git a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs
index c0c6f63374..116f27425d 100644
--- a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs
+++ b/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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs b/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs
index 05bef48a50..dca2356a9d 100644
--- a/src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs
+++ b/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)]
diff --git a/src/Tgstation.Server.Api/Models/Internal/Job.cs b/src/Tgstation.Server.Api/Models/Internal/Job.cs
index 8b3b210c60..29a44c7803 100644
--- a/src/Tgstation.Server.Api/Models/Internal/Job.cs
+++ b/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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs b/src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs
index 15fafe90b1..9341662df3 100644
--- a/src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs
+++ b/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; }
 	}
diff --git a/src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs b/src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs
index 998c519b19..3682306335 100644
--- a/src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs
+++ b/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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs b/src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs
index 89238b3099..6ea4ee92f3 100644
--- a/src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs b/src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs
index 036124c2a1..7b3a26cf33 100644
--- a/src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs b/src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs
index 20a2821d07..d936f9f026 100644
--- a/src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs
+++ b/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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs b/src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs
index 9f049e4814..ea587a9d63 100644
--- a/src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/NamedEntity.cs b/src/Tgstation.Server.Api/Models/NamedEntity.cs
index a138ef7eb5..930ca9c6e3 100644
--- a/src/Tgstation.Server.Api/Models/NamedEntity.cs
+++ b/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)]
diff --git a/src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs b/src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs
index ab34e28bde..c3bf7b8425 100644
--- a/src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs
+++ b/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; }
 
diff --git a/src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs b/src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs
index fbdd1f00a1..437dc6132a 100644
--- a/src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs
+++ b/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; }
 	}
 }
diff --git a/src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs b/src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs
index d0b86cdaa4..115d2c395e 100644
--- a/src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs
+++ b/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; }
 	}
diff --git a/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs b/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
index 70cb64c530..d58d81b6b4 100644
--- a/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
+++ b/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>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 053fe1f9aa..4e97485e95 100644
--- a/src/Tgstation.Server.Api/Models/Response/JobResponse.cs
+++ b/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; }
 	}
diff --git a/src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs b/src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs
index 05c05e8aa0..b39867b413 100644
--- a/src/Tgstation.Server.Api/Models/Response/LogFileResponse.cs
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs b/src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs
index df3d72595f..dc42fa230c 100644
--- a/src/Tgstation.Server.Api/Models/Response/PaginatedResponse.cs
+++ b/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; }
 	}
 }
diff --git a/src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs b/src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs
index 4e80e80564..82f27e7e7c 100644
--- a/src/Tgstation.Server.Api/Models/Response/ServerInformationResponse.cs
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs b/src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs
index 48c9b99e6a..46a96d8d49 100644
--- a/src/Tgstation.Server.Api/Models/Response/ServerUpdateResponse.cs
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/Response/TokenResponse.cs b/src/Tgstation.Server.Api/Models/Response/TokenResponse.cs
index f81066741a..ddc757dfd0 100644
--- a/src/Tgstation.Server.Api/Models/Response/TokenResponse.cs
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/TestMergeParameters.cs b/src/Tgstation.Server.Api/Models/TestMergeParameters.cs
index 174bb6886b..22b4b5f28e 100644
--- a/src/Tgstation.Server.Api/Models/TestMergeParameters.cs
+++ b/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; }
diff --git a/src/Tgstation.Server.Api/Models/UserName.cs b/src/Tgstation.Server.Api/Models/UserName.cs
index a3b6be8162..00f9b4772a 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/3] 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 d415e30ea3..5c3c55313b 100644
--- a/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs
+++ b/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs
@@ -5,7 +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;
 using Microsoft.OpenApi.Any;
@@ -99,6 +99,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 +108,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 +371,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 +493,6 @@ namespace Tgstation.Server.Host.Utils
 			var productHeaderSchema = new OpenApiSchema
 			{
 				Type = "string",
-				Format = "productheader",
 			};
 
 			swaggerDoc.Components.Parameters.Add(ApiHeaders.ApiVersionHeader, new OpenApiParameter
@@ -541,6 +540,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);

From 108cd6567378382a4fcd8aea614fcd12a77ba160 Mon Sep 17 00:00:00 2001
From: LetterN <24603524+LetterN@users.noreply.github.com>
Date: Sat, 8 Feb 2025 15:51:19 +0800
Subject: [PATCH 3/3] thingies

---
 build/Version.props                                             | 2 +-
 .../Models/Response/ErrorMessageResponse.cs                     | 2 +-
 src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs         | 1 +
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/build/Version.props b/build/Version.props
index f5a77aabad..e1e94b6991 100644
--- a/build/Version.props
+++ b/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>
diff --git a/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs b/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
index d58d81b6b4..1df20f57cb 100644
--- a/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
+++ b/src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs
@@ -19,7 +19,7 @@ namespace Tgstation.Server.Api.Models.Response
 		/// <summary>
 		/// A human-readable description of the error.
 		/// </summary>
-		/// <example>Ooopsie, we did a fucky wucky!</example>
+		/// <example>Oopsie woopsie, we did a fucky wucky!</example>
 		public string? Message { get; set; }
 
 		/// <summary>
diff --git a/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs b/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs
index 5c3c55313b..8e5806f30c 100644
--- a/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs
+++ b/src/Tgstation.Server.Host/Utils/SwaggerConfiguration.cs
@@ -6,6 +6,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;