Change the swagger documentation path to /doc/tgs_api.json

Change hosted site path to `/documentation`

Closes #1586

.github/workflows/ci-pipeline.yml

@@ -478,7 +478,7 @@ jobs:
       uses: actions/upload-artifact@v3
       with:
         name: openapi-spec
-        path: C:/swagger.json
+        path: C:/tgs_api.json
 
     - name: Package Server Service
       if: ${{ matrix.configuration == 'Release' && matrix.watchdog-type == 'Basic' }}
@@ -706,7 +706,7 @@ jobs:
         path: ./swagger
 
     - name: Lint OpenAPI Spec
-      run: npx lint-openapi -v -p -c build/OpenApiValidationSettings.json ./swagger/swagger.json
+      run: npx lint-openapi -v -p -c build/OpenApiValidationSettings.json ./swagger/tgs_api.json
 
   upload-code-coverage:
     name: Upload Code Coverage
@@ -1311,7 +1311,7 @@ jobs:
         GITHUB_TOKEN: ${{ secrets.DEV_PUSH_TOKEN }}
       with:
         upload_url: ${{ steps.create_release.outputs.upload_url }}
-        asset_path: ./swagger/swagger.json
+        asset_path: ./swagger/tgs_api.json
         asset_name: swagger.json
         asset_content_type: application/json
 
@@ -1615,7 +1615,7 @@ jobs:
         GITHUB_TOKEN: ${{ secrets.DEV_PUSH_TOKEN }}
       with:
         upload_url: ${{ steps.create_release.outputs.upload_url }}
-        asset_path: ./swagger/swagger.json
+        asset_path: ./swagger/tgs_api.json
         asset_name: swagger.json
         asset_content_type: application/json
 

src/Tgstation.Server.Host/Configuration/GeneralConfiguration.cs

@@ -108,7 +108,7 @@ namespace Tgstation.Server.Host.Configuration
 		public bool UseBasicWatchdog { get; set; }
 
 		/// <summary>
-		/// If the swagger UI should be made avaiable.
+		/// If the swagger documentation and UI should be made avaiable.
 		/// </summary>
 		public bool HostApiDocumentation { get; set; }
 

src/Tgstation.Server.Host/Core/Application.cs

@@ -471,8 +471,15 @@ namespace Tgstation.Server.Host.Core
 
 			if (generalConfiguration.HostApiDocumentation)
 			{
-				applicationBuilder.UseSwagger();
-				applicationBuilder.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TGS API"));
+				applicationBuilder.UseSwagger(options =>
+				{
+					options.RouteTemplate = Routes.Root + "doc/{documentName}.{json|yaml}";
+				});
+				applicationBuilder.UseSwaggerUI(options =>
+				{
+					options.RoutePrefix = "documentation";
+					options.SwaggerEndpoint(Routes.Root + $"doc/{SwaggerConfiguration.DocumentName}.json", "TGS API");
+				});
 				logger.LogTrace("Swagger API generation enabled");
 			}
 

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

@@ -27,6 +27,11 @@ namespace Tgstation.Server.Host.Utils
 	/// </summary>
 	sealed class SwaggerConfiguration : IOperationFilter, IDocumentFilter, ISchemaFilter, IRequestBodyFilter
 	{
+		/// <summary>
+		/// The name of the swagger document.
+		/// </summary>
+		public const string DocumentName = "tgs_api";
+
 		/// <summary>
 		/// The <see cref="OpenApiSecurityScheme"/> name for password authentication.
 		/// </summary>
@@ -51,7 +56,7 @@ namespace Tgstation.Server.Host.Utils
 		public static void Configure(SwaggerGenOptions swaggerGenOptions, string assemblyDocumentationPath, string apiDocumentationPath)
 		{
 			swaggerGenOptions.SwaggerDoc(
-				"v1",
+				DocumentName,
 				new OpenApiInfo
 				{
 					Title = "TGS API",

src/Tgstation.Server.Host/appsettings.yml

@@ -13,7 +13,7 @@ General:
   UserGroupLimit: 25 # Maximum number of allowed groups
   InstanceLimit: 10 # Maximum number of allowed instances
   ValidInstancePaths: # An array of directories instances may be created in (either directly or as a subdirectory). null removes the restriction
-  HostApiDocumentation: false # Make HTTP API documentation available at /swagger/v1/swagger.json
+  HostApiDocumentation: false # Make HTTP API documentation available at /doc/tgs_api.json
   SkipAddingByondFirewallException: false # Windows Only: Prevent running netsh.exe to add a firewall exception for installed DreamDaemon binaries
   DeploymentDirectoryCopyTasksPerCore: 100 # Maximum number of concurrent file copy operations PER available CPU core
 Session:

tests/Tgstation.Server.Tests/Live/TestLiveServer.cs

@@ -1302,11 +1302,11 @@ namespace Tgstation.Server.Tests.Live
 						// Dump swagger to disk
 						// This is purely for CI
 						using var httpClient = new HttpClient();
-						var webRequestTask = httpClient.GetAsync(server.Url.ToString() + "swagger/v1/swagger.json", cancellationToken);
+						var webRequestTask = httpClient.GetAsync(server.Url.ToString() + "doc/tgs_api.json", cancellationToken);
 						using var response = await webRequestTask;
 						response.EnsureSuccessStatusCode();
 						await using var content = await response.Content.ReadAsStreamAsync(cancellationToken);
-						await using var output = new FileStream(@"C:\swagger.json", FileMode.Create);
+						await using var output = new FileStream(@"C:\tgs_api.json", FileMode.Create);
 						await content.CopyToAsync(output, cancellationToken);
 					}